Get a Record (Single)
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 retrieve a specific record using the kintone REST API.
To retrieve multiple records, a different endpoint is used. For more details, refer to the following page:
When Using from kintone
When executing the REST API as a JavaScript customization in kintone, you can easily execute the REST API 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.
/**
* Retrieve a record that matches the ID using the kintone REST API
*
* @param { Object } params
* @param { string | number } params.app - App ID
* @param { string | number } params.id - Record ID
* @return { Promise<{ record: Record<string, any>}> } - Record information
*/
const getRecord = (params) => {
const { app, id } = params;
return kintone.api(kintone.api.url('/k/v1/record.json', true), 'GET', { app, id });
};
Note that to retrieve multiple records, you specify records.json, but to retrieve a single record, you specify record.json.
Specify the app ID of the target and the record ID you want to retrieve as arguments.
If the target record exists, an object with a record property will be returned.
(() => {
const getRecord = (params) => {
/** Omitted */
};
kintone.events.on(['app.record.detail.show'], async (event) => {
const recordId = kintone.app.record.getId();
const appId = kintone.app.getId();
const { record } = await getRecord({ app: appId, id: recordId });
console.log(record); // { Field Code: Value, ... }
return event;
});
})();
(() => {
const getRecord = (params) => {
/** Omitted */
};
kintone.events.on(['app.record.index.show'], async (event) => {
const recordId = prompt('Please enter the ID of the record you want to retrieve');
const appId = kintone.app.getId();
const { record } = await getRecord({ app: appId, id: recordId });
console.log(record); // { Field Code: Value, ... }
return event;
});
})();
On the record detail or edit screen, you can easily retrieve record information using the kintone.app.record.get method.
If you only need to get the current state of the currently displayed record, it is recommended to use the kintone.app.record.get method.
To retrieve information of other records, not just the currently displayed record, you can use the REST API for more flexible data retrieval.
When Using from Outside kintone
The kintone REST API can be used from various environments such as Excel, GAS, Node.js, etc.
By using the REST API, you can operate applications using kintone data from environments other than kintone.
When retrieving 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.
When 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.
/**
* Retrieve a record that matches the ID using the kintone REST API
* @param { Object } params
* @param { string | number } params.app - App ID
* @param { string | number } params.id - Record ID
* @return { Promise<{ record: Record<string, any>}> } - Record information
*/
const getRecord = (params) => {
const { app, id } = params;
return fetch(`https://__your_subdomain__.cybozu.com/k/v1/record.json?app=${app}&id=${id}`, {
method: 'GET',
headers: {
'X-Cybozu-API-Token': 'YOUR_API_TOKEN',
},
}).then((res) => res.json());
};
Replace __your_subdomain__ and YOUR_API_TOKEN with your own environment settings.
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.
When Using GAS
When using the kintone REST API from Google Apps Script (GAS), you can send HTTP requests using the UrlFetchApp class.
/**
* Retrieve a record that matches the ID using the kintone REST API
* @param { Object } params
* @param { string | number } params.app - App ID
* @param { string | number } params.id - Record ID
* @return { { record: Record<string, any> } } - Record information
*/
const getRecord = (params) => {
const { app, id } = params;
const url = `https://__your_subdomain__.cybozu.com/k/v1/record.json?app=${app}&id=${id}`;
const options = {
method: 'GET',
headers: {
'X-Cybozu-API-Token': 'YOUR_API_TOKEN',
},
};
const response = UrlFetchApp.fetch(url, options);
return JSON.parse(response.getContentText());
};
When Using Python
When using the kintone REST API from Python, you can send HTTP requests using the requests library.
import requests
def get_record(app: str, record_id: str) -> dict:
url = f'https://__your_subdomain__.cybozu.com/k/v1/record.json?app={app}&id={record_id}'
headers = {
'X-Cybozu-API-Token': 'YOUR_API_TOKEN',
}
response = requests.get(url, headers=headers)
return response.json()
When Using Command Line
When using the kintone REST API from the command line, you can send HTTP requests using the curl command.
curl -X GET 'https://__your_subdomain__.cybozu.com/k/v1/record.json?app=__app_id__&id=__record_id__' \
-H 'X-Cybozu-API-Token: __your_api_token__'