Field Types

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.

UI.png

 

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

  • 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"
			]
		}
	
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"
                }
            }
        }
    ]
}
	
  • 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 Radio button fields.

FIELD TYPE VALUE
  • Check box
  • Multi-choice
  • Attachment
  • User selection
  • Table
  • Categories
"value":[]
  • Date
  • Time
  • Drop-down
  • Radio button
"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
Do you have any questions or issues related to this article?
Please share your views with us in the Community forums!