Get Form

Retrieves the form details of an App.

caution
Attention

This API URL path only supports the retrieval of form data. For APIs that have similar functionalities that also support related Update methods, refer to the following APIs:
Get Form Fields API
Get Form Layout APIs

In addition, the Kintone Config Helper tool can also be used to retrieve field information from Apps. For more information, refer to the following article:
Kintone Config Helper

Get Form

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

MethodGET
URLhttps://{subdomain}.kintone.com/k/v1/form.json
URL(guest space)https://{subdomain}.kintone.com/k/guest/{SpaceID}/v1/app/form.json
Authentication Password Authentication , API Token Authentication , Session Authentication
Content-Typeapplication/json

Contents

Permissions

  • Permission to view records or add records is needed.

Request Parameters

Parameter Value Required Description
app Integer or String Yes The App ID.

Sample Request

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"
}

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

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"
    }
  ]
}

JavaScript Samples

1
2
3
4
5
6
7
8
kintone.api(kintone.api.url('/k/v1/form.json', 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();

Pre-live settings

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

URL https://{subdomain}.kintone.com/k/v1/preview/form.json
URL(guest space) 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.json', 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}.kintone.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();

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.