Field Types

Last Updated:
Follow

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. When you are creating, retrieving and updating data via API, you will need to know the Field Codes of the fields.
To check or change the Field Codes, hover over your fields in the app's settings, and open up the settings menu from the cog wheel that appears.

UI.png

 

The Field Codes for the below fields though 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 though when creating/updating tables using JavaScript API, where there are some cases you will need to specify the TYPE.

The "value" specifies the value the field holds, or will hold, depending on what API you use.

The Record number and the Record ID

These two fields sound alike, but make sure to understand the difference before moving on. If you don't alter the App Code settings in your app though, these two fields should give you 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.
    The format though 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

  • 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"
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"
			]
		}
Single choice 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"
        ]
}

Single choice
*

 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"
                }
            }
        }
    ]
}
  • 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 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 Single-choice fields.

FIELD TYPE VALUE
  • Check box
  • Multi-choice
  • Attachment
  • User selection
  • Table
  • Categories
 
"value":[]
  • Date
  • Time
  • Drop-down
  • Single-choice
 
"value":null
  • Text
  • Text Area
  • Rich text
  • Number
  • Calculated
  • Link
  • Date and time
  • Lookup
  • Status
 
"value":""
Was this article helpful?
0 out of 0 found this helpful
Comments
Please sign in to leave a comment.