API Docs

Field Types

Contents

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.
For more information, refer to the following document:
Overview of Field Codes (External link)

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 the App Code is set to "APPCODE", the Record Number will be displayed 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 using Kintone APIs.

Fields for Form Formatting

The following are fields to customize forms. To get/add/update values is not possible.

  • Label
  • Blank space
  • Border
  • Field group

Use the following APIs to get or modify the forms' settings:

It is not possible to get/add/update values from the Related records field.

Use the following APIs to get or modify the forms' settings:

Number Fields

When using Kintone JavaScript API, the values that can be retrieved or modified in number fields are as follows:

  • Numbers
    • + or - can be used to express positive and negative values.
    • . can be used to express decimals.
    • e or E can be used to express exponentials.
  • Whitespaces

When using kintone.app.record.set() or an event object to update the value, the following values can be used:

  • undefined, null: The value in the Number field will become empty.
  • #INVALID!: The value in the Number field will not be changed.

Entering an invalid value in the Number field will return #INVALID!.

For more information on kintone.app.record.set(), refer to the following article:
Set Record Value

Field Responses

Replace <field_code> with the appropriate field code.

Fields Related to Record Information

FIELD TYPE SAMPLE RESPONSE
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

Custom Fields

FIELD TYPE SAMPLE RESPONSE
Text SINGLE_LINE_TEXT 
"<field_code>": {
  "type": "SINGLE_LINE_TEXT",
  "value": "Hello Kintone"
}
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>"
}
Number NUMBER 
"<field_code>": {
  "type": "NUMBER",
  "value": "777"
}
Reference: Number Fields
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: 2024-08-26T08:16:39Z
  • Date: 2024-08-26
  • Time: 08:16
  • Hours & minutes: 49:30 (49 hours 30 minutes)
  • Days & hours & minutes: 49:30 (2 days 1 hour 30 minutes)
The value of value are empty strings for the following events:
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"
}
Multi-choice MULTI_SELECT 
"<field_code>": {
  "type": "MULTI_SELECT",
  "value": [
    "Choice 1",
    "Choice 2"
  ]
}
Drop-down DROP_DOWN 
"<field_code>": {
  "type": "DROP_DOWN",
  "value": "Choice 1"
}
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"
    }
  ]
}
Date DATE 
"<field_code>": {
  "type": "DATE",
  "value": "2015-04-15"
}
Reference: Date Formats
Time TIME 
"<field_code>": {
  "type": "TIME",
  "value": "09:00"
}
Reference: Date Formats
Date and time DATETIME 
"<field_code>": {
  "type": "DATETIME",
  "value": "2015-03-17T10:20:00Z"
}
Reference: Date Formats
Link LINK 
"<field_code>": {
  "type": "LINK",
  "value": "https://www.kintone.com/"
}
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.
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"
          ]
        }
      }
    }
  ]
}
Related records REFERENCE_TABLE Values for this field cannot be retrieved.
Categories CATEGORY 
"Categories": {
  "type": "CATEGORY",
  "value": [
    "category1",
    "category2"
  ]
}
Status (Process management status) STATUS 
"Status": {
  "type": "STATUS",
  "value": "Not started"
}
Assignee (Assignee of the process management status) STATUS_ASSIGNEE 
"Assignee": {
  "type": "STATUS_ASSIGNEE",
  "value": [
    {
      "code": "john-d",
      "name": "John Doe"
    }
  ]
}
Label LABEL Values for this field cannot be retrieved.
Blank space SPACER Values for this field cannot be retrieved.
Border HR Values for this field cannot be retrieved.
Field group GROUP Values for this field cannot be retrieved.

Field Requests

Replace <field_code> with the appropriate field code.

Field Related to Record Information

FIELD TYPE SAMPLE REQUEST
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 For Kintone users:
"<field_code>": {
  "value": {
    "code": "john-d"
  }
}
For guest users:
"<field_code>": {
  "value": {
    "code": "guest/ab@kintone.com"
  }
}
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 For Kintone users:
"<field_code>": {
  "value": {
    "code": "john-d"
  }
}
For guest users:
"<field_code>": {
  "value": {
    "code": "guest/ab@kintone.com"
  }
}
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

Custom Fields

FIELD TYPE SAMPLE REQUEST
Text SINGLE_LINE_TEXT 
"<field_code>": {
  "value": "This is Kintone"
}
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>\"
}
Number NUMBER 
"<field_code>": {
  "value": "111"
}
Reference: Number Fields
Calculated CALC Values for this field cannot be created or updated.
Check box * CHECK_BOX 
"<field_code>": {
  "value": [
    "Choice1",
    "Choice2"
  ]
}
Radio button * RADIO_BUTTON 
"<field_code>": {
  "value": "Choice3"
}
If an empty string is specified, the default value is set.
Multi-choice * MULTI_SELECT 
"<field_code>": {
  "value": [
    "Choice1",
    "Choice2"
  ]
}
Drop-down * DROP_DOWN 
"<field_code>": {
  "value": "Choice3"
}
User selection USER_SELECT For Kintone users:
"<field_code>": {
  "value": [
   { "code": "john-d" },
   { "code": "jane-r" }
  ]
}
For guest users:
"<field_code>": {
  "value": [
    { "code": "guest/ab@kintone.com" },
    { "code": "guest/cd@kintone.com" }
  ]
}
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"
    }
  ]
}
Date DATE 
"<field_code>": {
  "value": "2015-04-15"
}
Reference: Date Formats
Time TIME 
"<field_code>": {
  "value": "09:00"
}
Reference: Date Formats
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
Link LINK 
"<field_code>": {
  "value": "https://www.kintone.com/"
}
Attachment FILE 
"<field_code>": {
  "type": "FILE",
  "value": [
    {
      "fileKey":"20150417022053715283FF97DC413CBC4B7A41C",
    },
    {
      "fileKey": "20150417022159ECFC1223C4B34C939E1B9BD25",
    }
  ]
}
Lookup SINGLE_LINE_TEXT or NUMBER
(This depends on the field type of the 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"
        }
      }
    }
  ]
}
Do not add large numbers of rows to a single table. Depending on the App’s settings, the load will affect the records processing, including the records display and operations using the REST API.
For notes on working with tables via the REST API or JavaScript API, refer to the following section:
Notes on Operating Table's Field Types
Related records REFERENCE_TABLE Values for this field cannot be created or updated.
Categories CATEGORY Values for this field cannot be created or updated.
Status (Process management status) STATUS Values for this field cannot be created or updated.
Assignee (Assignee of the process management status) STATUS_ASSIGNEE Values for this field cannot be created or updated.
Label LABEL Values for this field cannot be created or updated.
Blank space SPACER Values for this field cannot be created or updated.
Border HR Values for this field cannot be created or updated.
Field Group GROUP Values for this field cannot be created or updated.

*For the value, specify the options configured in the field's settings (deleted options can still be specified via API or CSV).

Notes on Operating Table Field

Adding or updating via Kintone JavaScript API
  • When adding or updating a table, specify the values of all existing rows.
  • The order of the rows is the order of the request data.
  • The field type must be specified when adding or updating a table:
    Overwrite field values
Adding or updating via Kintone REST API
  • When adding or updating a table, specify the values of all existing rows.
  • When the id is specified, the value of the specified row will be updated.
  • The order of the rows is the order of the request data.
  • To reorder the rows, the request data should be prepared with the reordered id of the rows.
Adding or deleting of rows

Rows can be added to or removed from a table by adding or deleting row objects in the table’s value parameter.

An example of adding a row with push():

1

record['table']['value'].push(row);

An example of deleting a row with pop():

1

record['table']['value'].pop();

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 EMPTY VALUE REQUEST
  • Text
  • Text Area
  • Drop-down
  • Link
  • Date and time
  • Lookup
  • Rich 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