Add a Record (Single)
kintone offers a rich set of APIs that allow you to directly manipulate application data programmatically.
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 add a single record using the kintone REST API.
To add multiple records, a different endpoint is used. For details, please refer to the following page:
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 REST API endpoint without worrying about the execution space.
/**
* Add a record to an app using the kintone REST API
*
* @param { Object } params
* @param { string | number } params.app - App ID
* @param { Record<string, any> } params.record - Record information to be added
* @return { Promise<{ id: string; revision: "1" }> } - The ID and revision number of the added record
*/
const addRecord = (params) => {
const { app, record } = params;
return kintone.api(kintone.api.url('/k/v1/record.json', true), 'POST', { app, record });
};Note that when adding multiple records, specify records.json, but when adding a single record, specify record.json.
Specify the app ID of the destination and the record information to be added as arguments.
If the addition is successful, an object with id and revision properties will be returned.
In record, use the field code of each field as the key and specify the value in the form { value: ... }. Fields you do not specify receive the default values configured in the app.
When using an API token, the token must have the “Add records” permission. The request also fails if a required field is empty or if a value violates a field’s input restrictions (such as prohibit duplicate values, character limits, or available options).
(() => {
const addRecord = (params) => {
/** Omitted */
};
kintone.events.on(['app.record.detail.show'], async (event) => {
const { record: currentRecord } = kintone.app.record.get();
const appId = kintone.app.getId();
await addRecord({
app: appId,
record: {
...currentRecord,
CopyFlag: { value: ['Copy'] },
},
});
return event;
});
})();(() => {
const addRecord = (params) => {
/** Omitted */
};
kintone.events.on(['app.record.index.show'], async (event) => {
const input = prompt('Please enter the record information to register');
const appId = kintone.app.getId();
await addRecord({
app: appId,
record: {
FieldCode: { value: input },
},
});
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.
When obtaining kintone data from environments other than kintone, you need to include authentication information in the request.
There are several types of authentication information, but by choosing an API token, you can easily obtain authentication information while ensuring security.
The simplest method is to use an ID and password, but due to security risks, it is recommended to use an API token with the minimum necessary permissions.
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.
/**
* Add a record to an app using the kintone REST API
*
* @param { Object } params
* @param { string | number } params.app - App ID
* @param { Record<string, any> } params.record - Record information to be added
* @return { Promise<{ id: string; revision: "1" }> } - The ID and revision number of the added record
*/
const addRecord = async (params) => {
const { app, record } = params;
const url = `https://__your_subdomain__.cybozu.com/k/v1/record.json`;
const options = {
method: 'POST',
headers: {
'Content-Type': 'application/json',
'X-Cybozu-API-Token': 'YOUR_API_TOKEN',
},
body: JSON.stringify({ app, record }),
};
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.
You can set these 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/record.json.
Using GAS
When using the kintone REST API from Google Apps Script (GAS), you can send HTTP requests using the UrlFetchApp class.
/**
* Add a record to an app using the kintone REST API
*
* @param { Object } params
* @param { string | number } params.app - App ID
* @param { Record<string, any> } params.record - Record information to be added
* @return { Promise<{ id: string; revision: "1" }> } - The ID and revision number of the added record
*/
const addRecord = (params) => {
const { app, record } = params;
const url = `https://__your_subdomain__.cybozu.com/k/v1/record.json`;
const options = {
method: 'POST',
headers: {
'X-Cybozu-API-Token': 'YOUR_API_TOKEN',
},
contentType: 'application/json',
payload: JSON.stringify({ app, record }),
};
const response = UrlFetchApp.fetch(url, options);
return JSON.parse(response.getContentText());
};Using the Command Line
When using the kintone REST API from the command line, you can send HTTP requests using the curl command.
curl -X POST https://__your_subdomain__.cybozu.com/k/v1/record.json \
-H 'Content-Type: application/json' \
-H 'X-Cybozu-API-Token: YOUR_API_TOKEN' \
-d '{
"app": "1",
"record": {
"FieldCode": { "value": "Value" }
}
}'