API Docs

Get Form

Retrieves the form details of an App.

caution
Attention

This API URL path only supports the retrieval of form data. Also check the Get Form Fields API and the Get Form Layout APIs. These APIs have similar functionalities to the Get Form API, but also support related Update methods. Kintone Config Helper is also a tool developers can use for retrieving field information from Apps.

Contents

Get Form - GET /form.json

Retrieves the form details of an app.
This includes details such as field names, field settings, default values etc.

URI

https://{subdomain}.kintone.com/k/v1/form.json

URI for Guest Space Apps

https://{subdomain}.kintone.com/k/guest/{SpaceID}/v1/form.json

Request Parameters

PARAMETER VALUE REQUIRED DESCRIPTION
app Integer Yes The App ID.

Sample Reqeust

Sample Request using Query Strings

Send the "app" parameter as an HTTP query string.

Query String
1

app=4
Request Header
1
2
3

GET https://example.kintone.com/k/v1/form.json?app=4 HTTP/1.1
Host: example.kintone.com:443
X-Cybozu-Authorization: a2ludG9uZTpkZXZlbG9wZXI=
Sample Request using JSON
Request Header
1
2
3
4

GET /k/v1/form.json HTTP/1.1
Host: example.kintone.com:443
X-Cybozu-Authorization: a2ludG9uZTpkZXZlbG9wZXI=
Content-Type: application/json
Body
1
2
3

{
  "app": "4"
}

Sample Response

Field properties of each field in the apps are returned as JSON data。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40

{
  "properties": [
    {
      "code": "string_1",
      "defaultValue": "",
      "expression": "",
      "hideExpression": "false",
      "maxLength": "64",
      "minLength": null,
      "label": "string_1",
      "noLabel": "false",
      "required": "true",
      "type": "SINGLE_LINE_TEXT",
      "unique": "true"
    },
    {
      "code": "number_1",
      "defaultValue": "12345",
      "digit": "true",
      "displayScale": "4",
      "expression": "",
      "maxValue": null,
      "minValue": null,
      "label": "number_1",
      "noLabel": "true",
      "required": "false",
      "type": "NUMBER",
      "unique": "false"
    },
    {
      "code": "checkbox_1",
      "defaultValue": ["sample1", "sample3"],
      "label": "checkbox_1",
      "noLabel": "false",
      "options": ["sample1", "sample2", "sample3"],
      "required": "false",
      "type": "CHECK_BOX"
    }
  ]
}

Response Parameters

PROPERTY NAME key VALUES SAMPLE
Field Name label String (will not be empty) 
"label": "title"
Field Code code String (will not be empty) 
"code": "field code"
Element ID elementId String (will not be empty) 
"elementId": "Space"
Field Type type The TYPE listed in the "Properties retrieved by each field" table below. 
"type": "CHECK_BOX"
Hide field name noLabel "true" or "false" 
"noLabel": "true"
Required Field required "true" or "false" 
"required": "true"
Prohibit duplicate values unique "true" or "false" 
"unique": "true"
Limits of Value maxValue Integer or null 
"maxValue": "1"
minValue Integer or null 
"minValue": "100"
Number of Characters maxLength Integer or null 
"maxLength": "5"
minLength Integer or null 
"minLength": "2"
Default Value defaultValue String or Empty String or null 
"defaultValue": "this is the default"

If several default values can be set, an array with those values will be returned
Default Value(time related) defaultExpression "NOW" or null 
"defaultExpression": "NOW"

If the " Default to the record creation date." setting is turned on, "NOW" will be returned. In this case, defaultValue will be NULL.
Options(for fields with selections) options Array of Strings(will not be an empty string) 
"options": ["A","B","C"]
Formula expression String or "" 
"expression": "price * amount"

Formulas are written with field codes.
Use thousands separators digit "true" or "false" 
"digit": "true"
Type(Link) protocol
  • "WEB" (URL)
  • "CALL" (Telephone number)
  • "MAIL" (E-mail address)
 
"protocol": "WEB"
Show As format
  • "NUMBER" (Number)
  • "NUMBER_DIGIT" (Number with thousands separator)
  • "DATETIME" (Date & time)
  • "DATE" (Date)
  • "TIME" (Time)
  • "HOUR_MINUTE" (Hours & minutes)
  • "DAY_HOUR_MINUTE" (Days & hours & minutes)
 
"format": "NUMBER"
Number of Decimal Places displayScale The number of decimal places or null 
"displayScale": "4"
Hide formula hideExpression "true" or "false" 
"hideExpression": "false"
Datasource App ID (for Lookup, Related Records) relatedApp Integer or null (null if you don't have permission to manage the Datasource App)
 
"relatedApp": "123"
Fields within tables fields Array 
"fields": [
  {
    "code": "singlelinetext_in_table",
    "defaultValue": "",
    "expression": "",
    "hideExpression": "false",
    "maxLength": "64",
    "minLength": null,
    "label": "Full Name",
    "noLabel": "false",
    "required": "true",
    "type": "SINGLE_LINE_TEXT",
    "unique": "true"
  },
  {
    "code": "integer_in_table",
    "defaultValue": "25",
    "digit": "false",
    "displayScale": null,
    "expression": "",
    "maxValue": null,
    "minValue": null,
    "label": "Age",
    "noLabel": "true",
    "required": "false",
    "type": "NUMBER",
    "unique": "false"
  }
]
Currency unit String or null (if not set) 
"unit": "$"
Prefix/Suffix unitPosition "BEFORE" (Prefix)
"AFTER" (Suffix)
The default is set to "Before".		 
"unitPosition": "BEFORE"

Properties retrieved by each field

FIELD TYPE TYPE PROPERTIES THAT ARE RETRIEVED
Label LABEL
  • Field Name
  • Field Type
Single-line text SINGLE_LINE_TEXT or NUMBER (Depends on the settings of the Lookup field)
  • Field Name
  • Field Code
  • Field Type
  • Required Field
  • Hide field name
  • Prohibit duplicate values
  • Number of Characters
  • Default Value
  • Formula
  • Hide formula
Number NUMBER
  • Field Name
  • Field Code
  • Field Type
  • Required Field
  • Hide field name
  • Prohibit duplicate values
  • Limits of Value
  • Default Value
  • Use thousands separators
  • Number of Decimal Places
Calculated CALC
  • Field Name
  • Field Code
  • Field Type
  • Required Field （always false）
  • Hide field name
  • Formula
  • Show As
  • Number of Decimal Places
  • Hide formula
Multi-line text MULTI_LINE_TEXT
  • Field Name
  • Field Code
  • Field Type
  • Required Field
  • Hide field name
  • Default Value
Rich text RICH_TEXT
  • Field Name
  • Field Code
  • Field Type
  • Required Field
  • Hide field name
  • Default Value
Check box CHECK_BOX
  • Field Name
  • Field Code
  • Field Type
  • Required Field
  • Hide field name
  • Default Value
  • Options
Radio button RADIO_BUTTON
  • Field Name
  • Field Code
  • Field Type
  • Required Field （always true）
  • Hide field name
  • Options
  • Default Value
Drop-down DROP_DOWN
  • Field Name
  • Field Code
  • Field Type
  • Required Field
  • Hide field name
  • Options
  • Default Value
Multi-choice MULTI_SELECT
  • Field Name
  • Field Code
  • Field Type
  • Required Field
  • Hide field name
  • Options
  • Default Value
Attachment FILE
  • Field Name
  • Field Code
  • Field Type
  • Required Field
  • Hide field name
Date DATE
  • Field Name
  • Field Code
  • Field Type
  • Required Field
  • Hide field name
  • Prohibit duplicate values
  • Default Value
  • Default Value(time related)
Time TIME
  • Field Name
  • Field Code
  • Field Type
  • Required Field
  • Hide field name
  • Default Value
  • Default Value(time related)
Date and time DATETIME
  • Field Name
  • Field Code
  • Field Type
  • Required Field
  • Hide field name
  • Prohibit duplicate values
  • Default Value
  • Default Value(time related)
Link LINK
  • Field Name
  • Field Code
  • Field Type
  • Required Field
  • Hide field name
  • Prohibit duplicate values
  • Type(Link)
  • Number of Characters
  • Default Value
Blank Space SPACER
  • Element ID
  • Field Type
Border HR
  • Field Type
User selection USER_SELECT
  • Field Name
  • Field Code
  • Required Field
  • Field Type
  • Hide field name
Department Selection ORGANIZATION_SELECT
  • Field Name
  • Field Code
  • Required Field
  • Field Type
  • Hide field name
Group Selection GROUP_SELECT
  • Field Name
  • Field Code
  • Required Field
  • Field Type
  • Hide field name
Lookup SINGLE_LINE_TEXT
  • Field Name
  • Field Code
  • Required Field
  • Hide field name
  • Datasource App ID
  • Field type of Key Field
Related Records REFERENCE_TABLE
  • Field Name
  • Field Code
  • Field Type
  • Hide field name
  • Datasource App ID
Record number RECORD_NUMBER
  • Field Name
  • Field Code
  • Field Type
  • Hide field name
Created by CREATOR
  • Field Name
  • Field Code
  • Field Type
  • Hide field name
Created datetime CREATED_TIME
  • Field Name
  • Field Code
  • Field Type
  • Hide field name
Updated by MODIFIER
  • Field Name
  • Field Code
  • Field Type
  • Hide field name
Updated datetime UPDATED_TIME
  • Field Name
  • Field Code
  • Field Type
  • Hide field name
Table SUBTABLE
  • Field Code
  • Field Type
  • Field information within the table

Fields that cannot be retrieved

  • Categories
  • Status
  • Field Group
  • The following fields if inside of a field group:
    • Automatically generated fields (Record number, Created by, Created datetime, Updated by, Updated datetime), Blank space, Label, Border

JavaScript Samples

Kintone REST API Request Example
1
2
3
4
5
6
7
8

kintone.api(kintone.api.url('/k/v1/form', true), 'GET', {
  'app': kintone.app.getId()
}, function(resp) {
  console.log(resp);
}, function(error) {
  console.log(error);
}
);
XMLHttpRequest Example
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13

var apiurl = '/k/v1/form.json?app=' + kintone.app.getId();
var xhr = new XMLHttpRequest();
xhr.open('GET', apiurl, true);
xhr.onload = function() {
  if (xhr.status === 200) {
    console.log(JSON.parse(xhr.responseText));
  } else {
    console.log(xhr.status + ' ' + xhr.statusText);
    console.log(JSON.parse(xhr.responseText));
  }
};
xhr.setRequestHeader('X-Requested-With', 'XMLHttpRequest');
xhr.send();

Get Form Preview - GET /preview/form.json

Retrieves the form details of an app that is still undergoing changes, and the changes have not been applied.

URI

https://{subdomain}.kintone.com/k/v1/preview/form.json

URI for Guest Space Apps

https://{subdomain}.kintone.com/k/guest/{SpaceID}/v1/preview/form.json

Request parameters and response properties are the same as the Get Form API.

JavaScript Samples

Kintone REST API Request Example
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11

var body = {
  'app': 1
};

kintone.api(kintone.api.url('/k/v1/preview/form', true), 'GET', body, function(resp) {
  // success
  console.log(resp);
}, function(error) {
  // error
  console.log(error);
});
XMLHttpRequest Example
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16

var params = '?app=1';
var url = 'https://{subdomain}.cybozu.com/k/v1/preview/form.json' + params;
console.log(url);
var xhr = new XMLHttpRequest();
xhr.open('GET', url);
xhr.setRequestHeader('X-Requested-With', 'XMLHttpRequest');
xhr.onload = function() {
  if (xhr.status === 200) {
    // success
    console.log(JSON.parse(xhr.responseText));
  } else {
    // error
    console.log(JSON.parse(xhr.responseText));
  }
};
xhr.send();

Limitations

  • You must have permission to manage the app.

Note

This document mistakenly stated that this API was to be deprecated in the future.
There is no plan yet for the deprecation of this API. We apologize for inconveniences this may have caused for our Kintone developers.