To Start Off
Fields and their Field codes, Types, and Values
Fields follow the JSON format listed in the tables in the Field Responses and Field Requests below.
Each field in a Kintone app has a Field Code, that is unique within the App. These field codes are necessary when creating, retrieving, and updating data via API. To check or change the field code, hover over the field in the App's settings, and open up the settings menu from the cog wheel that appears.
The field codes for the below fields cannot be changed - in this case, specify the name of these fields when using the Kintone API.
- Categories
- Status
- Assignee
Kintone has various fields that can be placed inside the App - the type specifies what type of field the target belongs to. The type will be responded back when retrieving Kintone data, but will not be needed when creating or updating data.
*There is an exception when creating/updating tables using the JavaScript API, where in some cases the TYPE will need to be specified.
The value specifies the value the field holds, or will hold, depending on what API used.
The Record number and the Record ID
These two fields sound alike, but make sure to understand the difference before moving on. However, if the App Code settings are not altered, these two fields hold the same values.
- Record Number
A Record Number is a number automatically given to each record of an App.
The number is unique within the App, meaning that no two records in the App can have the same Record Number.
However, the format of the Record Number can be altered through the advanced settings of the App, by specifying an App Code. If you specify your App Code to be "APPCODE", then your Record Number will be in the following sample format: "APPCODE-1". - Record ID
The Record ID, rather much like the Record Number, is a number automatically given to each record of an App. The Record ID will always be a number.
Use the Record ID when you are using Kintone APIs.
Field Responses
FIELD | TYPE | SAMPLE RESPONSE (Replace <field_code> with your field's field code) |
---|---|---|
Record number | RECORD_NUMBER |
If an App Code is not set (default): "<field_code>": { "type": "RECORD_NUMBER", "value": "7" } If an App Code is set: "<field_code>": { "type": "RECORD_NUMBER", "value": "APPCODE-7" } |
Record ID | __ID__ |
"$id": { "type": "__ID__", "value": "3" } |
Revision | __REVISION__ |
"$revision": { "type": "__REVISION__", "value": "9" } |
Created by | CREATOR |
For kintone users: "<field_code>": { "type": "CREATOR", "value": { "code": "john-d", "name": "John Doe" } } For guest users: "<field_code>": { "type": "CREATOR", "value": { "code": "guest/ab@kintone.com", "name": "Alfred Bills" } } |
Created datetime | CREATED_TIME |
"<field_code>": { "type": "CREATED_TIME", "value": "2015-01-22T15:07:00Z" } |
Updated by | MODIFIER |
For kintone users: "<field_code>": { "type": "MODIFIER", "value": { "code": "john-d", "name": "John Doe" } } For guest users: "<field_code>": { "type": "MODIFIER", "value": { "code": "guest/ab@kintone.com", "name": "Alfred Bills" } } |
Updated datetime | UPDATED_TIME |
"<field_code>": { "type": "UPDATED_TIME", "value": "2015-01-22T15:07:00Z" } |
Text | SINGLE_LINE_TEXT |
"<field_code>": { "type": "SINGLE_LINE_TEXT", "value": "Hello Kintone" } |
Number | NUMBER |
"<field_code>": { "type": "NUMBER", "value": "777" } |
Calculated | CALC |
"<field_code>": { "type": "CALC", "value": "777888999" } The "value" will vary depending on the "Show as" option set on the field's settings
|
Text area | MULTI_LINE_TEXT |
"<field_code>": { "type": "MULTI_LINE_TEXT", "value": "Hello\nKintone" } |
Rich text | RICH_TEXT |
"<field_code>": { "type": "RICH_TEXT", "value": "<a href=\"https://www.kintone.com\">Kintone</a>" } |
Check box | CHECK_BOX |
"<field_code>": { "type": "CHECK_BOX", "value": [ "Choice 1", "Choice 2" ] } |
Radio button | RADIO_BUTTON |
"<field_code>": { "type": "RADIO_BUTTON", "value": "Choice 3" } |
Drop-down | DROP_DOWN |
"<field_code>": { "type": "DROP_DOWN", "value": "Choice 1" } |
Multi-choice | MULTI_SELECT |
"<field_code>": { "type": "MULTI_SELECT", "value": [ "Choice 1", "Choice 2" ] } |
Attachment | FILE |
"<field_code>": { "type": "FILE", "value": [ { "contentType": "text/plain", "fileKey":"20150417022053715283FF97DC413CBC4B7A41C", "name": "kintoneUpdates.txt", "size": "25302" }, { "contentType": "text/plain", "fileKey": "20150417022159ECFC1223C4B34C939E1B9BD25", "name": "APIUpdatestxt", "size": "20311" } ] } |
Link | LINK |
"<field_code>": { "type": "LINK", "value": "https://www.kintone.com/" } |
Date | DATE |
"<field_code>": { "type": "DATE", "value": "2015-04-15" } |
Time | TIME |
"<field_code>": { "type": "TIME", "value": "09:00" } |
Date and time | DATETIME |
"<field_code>": { "type": "DATETIME", "value": "2015-03-17T10:20:00Z" } |
User selection | USER_SELECT |
For kintone users: "<field_code>": { "type": "USER_SELECT", "value": [ { "code": "john-d", "name": "John Doe" }, { "code": "jane-r", "name": "Jane Roe" } ] } For guest users: "<field_code>": { "type": "USER_SELECT", "value": [ { "code": "guest/ab@kintone.com", "name": "Alfred Bills" }, { "code": "guest/cd@kintone.com", "name": "Cal Davis" } ] } |
Department Selection | ORGANIZATION_SELECT |
"<field_code>": { "type": "ORGANIZATION_SELECT", "value": [ { "code": "human_resources", "name": "Human Resources" }, { "code": "sales", "name": "Sales" } ] } |
Group Selection | GROUP_SELECT |
"<field_code>": { "type": "GROUP_SELECT", "value": [ { "code": "project_manager", "name": "Project Manager" }, { "code": "team_leader", "name": "Team Leader" } ] } |
Categories | CATEGORY |
"Categories": { "type": "CATEGORY", "value": [ "category1", "category2" ] } |
Status | STATUS |
"Status": { "type": "STATUS", "value": "Not started" } |
Assignee | STATUS_ASSIGNEE |
"Assignee": { "type": "STATUS_ASSIGNEE", "value": [ { "code": "john-d", "name": "John Doe" } ] } |
Lookup | SINGLE_LINE_TEXT or NUMBER *This depends on the field type of the Key Field. |
If the Key fields is a SINGLE_LINE_TEXT "<field_code>": { "type": "SINGLE_LINE_TEXT", "value": "Code003" } If the Key fields is a NUMBER "<field_code>": { "type": "NUMBER", "value": "10" } |
Table | SUBTABLE |
"<field_code>": { "type": "SUBTABLE", "value": [ { "id": "48277", "value": { "textfield_0": { "type": "SINGLE_LINE_TEXT", "value": "Hello Kintone 1" }, "numberfield_0": { "type": "NUMBER", "value": "5" }, "checkboxfield_0": { "type": "CHECK_BOX", "value": [ "Choice1" ] } } }, { "id": "48278", "value": { "textfield_0": { "type": "SINGLE_LINE_TEXT", "value": "Hello Kintone 2" }, "numberfield_0": { "type": "NUMBER", "value": "7" }, "checkboxfield_0": { "type": "CHECK_BOX", "value": [ "Choice2" ] } } } ] } |
Field Requests
FIELD | TYPE | SAMPLE REQUEST (Replace <field_code> with your field's field code) |
---|---|---|
Record number | RECORD_NUMBER | Values for this field cannot be created or updated. |
Record ID | __ID__ | Values for this field cannot be created or updated. |
Revision | __REVISION__ | Values for this field cannot be created or updated. |
Created by | CREATOR |
"<field_code>": { "value": { "code": "john-d" } } Values for this field cannot be updated. |
Created datetime | CREATED_TIME |
"<field_code>": { "value": "2015-01-22T23:07:00Z" } or "<field_code>": { "value": "2015-01-22T15:07:00-08:00" } Values for this field cannot be updated. Future dates and times cannot be set. |
Updated by | MODIFIER |
"<field_code>": { "value": { { "code": "john-d" } } } Values for this field cannot be updated. |
Updated datetime | UPDATED_TIME |
"<field_code>": { "value": "2015-01-22T15:07:00Z" } or "<field_code>": { "value": "2015-01-22T15:07:00-08:00" } Values for this field cannot be updated. Future dates and times cannot be set. |
Text | SINGLE_LINE_TEXT |
"<field_code>": { "value": "This is Kintone" } |
Number | NUMBER |
"<field_code>": { "value": "111" } |
Calculated | CALC | Values for this field cannot be created or updated. |
Text Area | MULTI_LINE_TEXT |
"<field_code>": { "value": "This is\nKintone" } |
Rich text | RICH_TEXT |
"<field_code>": { "value": "<a href=\"https://www.kintone.com\">Kintone</a>" } |
Check box |
CHECK_BOX |
"<field_code>": { "value": [ "Choice1", "Choice2" ] } |
Radio button |
RADIO_BUTTON |
"<field_code>": { "value": "Choice3" } |
Drop-down |
DROP_DOWN |
"<field_code>": { "value": "Choice3" } |
Multi-choice * |
MULTI_SELECT |
"<field_code>": { "value": [ "Choice1", "Choice2" ] } |
Attachment | FILE |
"<field_code>": { "type": "FILE", "value": [ { "fileKey":"20150417022053715283FF97DC413CBC4B7A41C", }, { "fileKey": "20150417022159ECFC1223C4B34C939E1B9BD25", } ] } |
Link | LINK |
"<field_code>": { "value": "https://www.kintone.com/" } |
Date | DATE |
"<field_code>": { "value": "2015-04-15" } |
Time | TIME |
"<field_code>": { "value": "09:00" } |
Date and time | DATETIME |
"<field_code>": { "value": "2015-03-17T18:20:00Z" } or "<field_code>": { "value": "2015-03-17T10:20:00-08:00" } |
User selection | USER_SELECT |
"<field_code>": { "value": [ { "code": "john-d" }, { "code": "jane-r" } ] } |
Department Selection | ORGANIZATION_SELECT |
"<field_code>": { "value": [ { "code": "human_resources" }, { "code": "sales" } ] } |
Group Selection | GROUP_SELECT |
"<field_code>": { "value": [ { "code": "project_manager" }, { "code": "team_leader" } ] } |
Categories | CATEGORY | Values for this field cannot be created or updated. |
Status | STATUS | Values for this field cannot be created or updated. |
Assignee | STATUS_ASSIGNEE | Values for this field cannot be created or updated. |
Lookup | SINGLE_LINE_TEXT or NUMBER *This depends on the field type of the Key Field. |
"<field_code>": { "value": "Code001" }Creating/updating of Lookup fields cannot be initiated with API tokens. The "Prohibit duplicate values" option must be checked for the Datasource App's key field. |
Table | SUBTABLE |
"<field_code>": { "value": [ { "id": "48277", "value": { "textfield_0": { "value": "Hello Kintone 1" }, "numberfield_0": { "value": "5" } } }, { "value": { "textfield_0": { "value": "Hello Kintone 2" }, "numberfield_0": { "value": "7" } } }, { "value": { "textfield_0": { "value": "Hello Kintone 3" }, "numberfield_0": { "value": "3" } } } ] }
|
*For the values, specify the options that you set up in the field's settings (deleted options can still be specified via API or CSV)
Empty Values
Fields with no values follow the rules in the table below. If you will state empty values in your fields, set the empty values for each field type.
You cannot set an empty value for Radio button fields.
FIELD TYPE | VALUE |
---|---|
|
"value":[] |
|
"value":null |
|
"value":"" |