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 update a specific record 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 update is successful.

(() => {
  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(',');

    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, you can send HTTP requests with almost the same code as executing JavaScript in the browser.

/**
 * 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) => {
  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 = UrlFetchApp.fetch(url, options);
  return JSON.parse(response.getContentText());
};

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.

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 { Promise<{}> } - An empty object if successful
 */
const deleteRecords = (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',
    },
    payload: JSON.stringify(params),
  };
  const response = UrlFetchApp.fetch(url, options);
  return JSON.parse(response.getContentText());
};

Limitations

When updating multiple records in kintone, the following limitations apply:

• The maximum number of records that can be deleted in a single request is 100

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