API Docs

Field Types

Contents

To Start Off

Fields and their Field codes, Types, and Values

Fields follow the JSON format listed in the tables in the following sections:

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"
}
Reference: Date Formats
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"
}
Reference: Date Formats
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
  • Number: "777888999"
  • Number with thousands separator: "777888999"
  • Date & time: "1994-08-26T08:16:39Z"
  • Date: "1994-08-26"
  • Time: "08:16"
  • Hours & minutes: "216080:16"
  • Days & hours & minutes: "216080:16"
The value of "value" are empty strings for the following events:
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"
    }
 ]
}
The fileKey included in the response can only be used for downloading files.
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"
}
Reference: Date Formats
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.
Reference: Date Formats
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.
Reference: Date Formats
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>": {Check box
  "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"
}
Reference: Date Formats
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"
}
The "Prohibit duplicate values" option must be checked for the source App's key field.
To use API tokens in Apps that contain Lookup fields, refer to the following article:
API Tokens - Limitations
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"
        }
      }
    }
  ]
}
  • When you want to update your tables or add more data, the API will first delete all rows of the table, and then add however many rows you stated in your JSON data. This means, if you already have 3 rows of table data, and you only specify 1 row in your JSON, your final table will output as 1 row of data, and not 4.
  • If you specify the "id" of a row in your JSON, you can update that specific row.
  • The JavaScript API works differently - if you are using JavaScript API to add rows, you will need to specify the field type in your JSON.
  • By adding or deleting a row object to/from the table's_value_ parameter, table rows can be added or deleted
    e.g.
    • Add a row: record['table']['value'].push(row);
    • Delete a row: record['table']['value'].pop();

*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 Value Responses

Empty Values are responded in the following ways:

FIELD TYPE RESPONDED EMPTY VALUE
  • Text
  • Text Area
  • Number
  • Date and time
  • Link
  • Lookup
 When using JavaScript APIs on the Record Add page and the Record Edit page
{ "value": undefined }
When using JavaScript APIs on other pages, or when using REST APIs
{ "value": "" }
  • Rich text
 When using JavaScript API or REST APIs
{ "value": "" }
  • Date
  • Time
 When using JavaScript APIs on the Record Add page and the Record Edit page
{ "value": undefined }
When using JavaScript APIs on other pages, or when using REST APIs
{ "value": null }
  • Drop-down
 When using REST APIs
{ "value": null }
When using JavaScript APIs on the Record Add page and the Record Edit page
{ "value": undefined }
When using JavaScript APIs on other pages
{ "value": "" }
  • Radio button
 When using REST APIs
{ "value": null }
When using JavaScript APIs
{ "value": "" }
  • Check box
  • Multi-choice
  • Attachment
  • User selection
  • Department selection
  • Group selection
  • Categories
  • Table
  • Assignee
 When using JavaScript APIs or REST APIs
{ "value": [] }

Empty Value Requests

Empty Values are requested in the following ways:

FIELD TYPE RESPONDED EMPTY VALUE
  • Text
  • Text Area
  • Drop-down
  • Link
  • Date and time
  • Lookup
  • Rixh Text
 
{ "value": "" }
or
{ "value": null }
  • Number
 
"value": ""
or
"value": undefined
or
"value": null
  • Date
  • Time
 
{ "value": null }
  • Check box
  • Multi-choice
  • Attachment
  • User selection
  • Department selection
  • Group selection
  • Table
 
{ "value": [] }
  • Radio button
  • Categories
  • Assignee
 N/A