Deleting Records

kintone offers a rich set of APIs that allow you to directly manipulate application data from your programs.

In particular, the REST API is a powerful tool for manipulating kintone data through HTTP requests.

This page provides a detailed explanation of how to delete records using the kintone REST API.

Incidentally, while there are separate APIs for retrieving, adding, and updating records, the method for deleting records is the same for both single and multiple records.

Using from kintone

When executing the REST API as a JavaScript customization in kintone, you can easily execute the REST API by using the provided JavaScript API.

By using the kintone.api.url method of the JavaScript API, you can obtain the endpoint of the REST API without worrying about the space in which it is executed.

/**
 * Delete records in an app using the kintone REST API
 *
 * @param { app: string | number; ids: number[]; revisions?: number[] } } params
 * @return { Promise<{}> } - An empty object if successful
 */
const deleteRecords = (params) => {
  return kintone.api(kintone.api.url('/k/v1/records.json', true), 'DELETE', params);
};

When deleting records, it is often the case that you want to delete records that match specific conditions.

Therefore, it might be a good idea to generalize the process of retrieving records that match specified conditions and then deleting those records.

/**
 * Retrieve records that match specified conditions using the kintone REST API
 *
 * @param { Object } params
 * @param { string | number } params.app - App ID
 * @param { string[] } params.fields - Field codes of the fields to retrieve
 * @param { string } params.query - Conditions for retrieving records
 * @param { boolean } params.totalCount - Whether to retrieve the total count of records
 * @return { Promise<{ records: Record<string, any>[]; totalCount: string | null }> } - Record information
 */
const getRecords = (params) => {
  const { app, fields, query, totalCount } = params;
  return kintone.api(kintone.api.url('/k/v1/records.json', true), 'GET', {
    app,
    fields,
    query,
    totalCount,
  });
};

const deleteRecords = (params) => {
  /** Omitted */
};

/**
 * Retrieve records that match specified conditions using the kintone REST API and delete them
 *
 * @param { Object } params
 * @param { string | number } params.app - App ID
 * @param { string } params.query - Conditions for retrieving records
 * @return { Promise<{}> } - Record information
 */
const deleteRecordsByQuery = async (params) => {
  const { app, query } = params;
  const fields = ['$id'];
  const { records } = await getRecords({ app, query, fields });

  const ids = records.map((record) => record.$id.value);

  return deleteRecords({ app, ids });
};

Specify the app ID and the information to identify the target for deletion as arguments.

By specifying the target record IDs as an array in the ids property, you can specify the records to be deleted.

Additionally, by specifying the revision numbers of the target records in the revisions property, you can ensure that deletion is performed only if the revision numbers match the expected values.

An empty object is returned if the deletion is successful.

You can specify up to 100 IDs in ids per request. Also, the getRecords call used to look up records returns at most 100 records when limit is not specified. To delete more than 100 records, see the Limitations section below.

(() => {
  const getRecords = (params) => {
    /** Omitted */
  };

  const deleteRecords = (params) => {
    /** Omitted */
  };

  kintone.events.on(['app.record.index.show'], async (event) => {
    const fieldCode = 'Field Code';
    const fieldValue = 'Value to Delete';
    const appId = kintone.app.getId();

    const query = `${fieldCode} = "${fieldValue}"`;
    const fields = ['$id'];
    const { records } = await getRecords({ app: appId, query, fields });

    const ids = records.map((record) => record.$id.value);

    await deleteRecords({ app: appId, ids });

    return event;
  });
})();

For the getRecords function used, please refer to the following page.

(() => {
  const deleteRecords = (params) => {
    /** Omitted */
  };

  kintone.events.on(['app.record.index.show'], async (event) => {
    const recordId = prompt('Enter the IDs of the records to delete, separated by commas');
    const appId = kintone.app.getId();

    const ids = recordId
      .split(',')
      .map((id) => id.trim())
      .filter(Boolean)
      .map(Number);

    await deleteRecords({ app: appId, ids });

    return event;
  });
})();

Using from outside kintone

The kintone REST API can be used from various environments such as Excel, GAS, and Node.js.

By using the REST API, you can operate applications using kintone data from environments other than kintone.

Using Node.js

When using the kintone REST API from Node.js (v18 or later), you can send HTTP requests with the standard fetch function.

/**
 * Delete records in an app using the kintone REST API
 *
 * @param { app: string | number; ids: number[]; revisions?: number[] } } params
 * @return { Promise<{}> } - An empty object if successful
 */
const deleteRecords = async (params) => {
  const url = `https://__your_subdomain__.cybozu.com/k/v1/records.json`;
  const options = {
    method: 'DELETE',
    headers: {
      'Content-Type': 'application/json',
      'X-Cybozu-API-Token': 'YOUR_API_TOKEN',
    },
    body: JSON.stringify(params),
  };
  const response = await fetch(url, options);
  if (!response.ok) {
    throw new Error(await response.text());
  }
  return response.json();
};

Replace __your_subdomain__ and YOUR_API_TOKEN with your own environment settings.

You can set them as arguments, but it is also fine to set them directly within the function.

Unlike the code used from kintone mentioned earlier, if the referenced app is in a guest space, you need to change the URL to /k/guest/{spaceId}/v1/records.json.

Using GAS

When using the kintone REST API from Google Apps Script (GAS), you can send HTTP requests using the UrlFetchApp class.

/**
 * Delete records in an app using the kintone REST API
 *
 * @param { app: string | number; ids: number[]; revisions?: number[] } } params
 * @return { Object } - An empty object if successful
 */
const deleteRecords = (params) => {
  const url = `https://__your_subdomain__.cybozu.com/k/v1/records.json`;
  const options = {
    method: 'DELETE',
    headers: {
      'X-Cybozu-API-Token': 'YOUR_API_TOKEN',
    },
    contentType: 'application/json',
    payload: JSON.stringify(params),
  };
  const response = UrlFetchApp.fetch(url, options);
  return JSON.parse(response.getContentText());
};

Limitations

When deleting records in kintone, the following limitations apply:

• The maximum number of records that can be deleted in a single request is 100
• When using an API token, the token must have the “Delete records” permission

For methods to delete records without being aware of this limitation, please refer to the following page.