Get Form Fields

Gets the list of fields and field settings of an App.

MethodGET
URLhttps://{subdomain}.kintone.com/k/v1/app/form/fields.json
URL(guest space)https://{subdomain}.kintone.com/k/guest/{SpaceID}/v1/app/form/fields.json
Authentication Password Authentication, API Token Authentication, Session Authentication
Content-Typeapplication/json (not needed if specifying the query with a query string)

Contents

Pre-live settings

Apps may hold pre-live settings that have not yet been deployed to the live App.
Access the pre-live settings with the below URL.

URL https://{subdomain}.kintone.com/k/v1/preview/app/form/fields.json
URL(guest space) https://{subdomain}.kintone.com/k/guest/{SpaceID}/v1/preview/app/form/fields.json

Permissions

  • Permission to view records or add records is needed when obtaining data of live apps.
  • Permission to manage the App is needed when obtaining data of pre-live settings.

Request Parameters

Parameter Value Required Description
app Integer Yes The App ID.
lang String The localized language to retrieve the data in:
  • default: retrieves the default names
  • en: retrieves the localized English names
  • zh: retrieves the localized Chinese names
  • ja: retrieves the localized Japanese names
  • user: retrieves the localized names, in the same language as the language setting* set on the user used for the authentication.
If ignored, the default names will be retrieved.

*If the user language setting is set to "Use Web browser settings", the settings set in the Accept-Language header will be used. If there is no Accept-Language header, the language set in the "Localization" settings in the System Administrator's menu will be used.

Sample Request

JavaScript (using Kintone REST API Request)

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
var body = {
  'app': 1
};

kintone.api(kintone.api.url('/k/v1/app/form/fields.json', true), 'GET', body, function(resp) {
  // success
  console.log(resp);
}, function(error) {
  // error
  console.log(error);
});

XMLHttpRequest

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
var url = 'https://{subdomain}.kintone.com/k/v1/app/form/fields.json?app=1';

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();

Response Parameters

Parameter Type Description
properties Object An object with data of the field settings.
properties.{fieldcode}.label String The field name.
properties.{fieldcode}.code String The field code.
properties.{fieldcode}.type String The field type.
  • GROUP: Group
  • GROUP_SELECT: Group selection
  • CALC: Calculated
  • CATEGORY: Category
  • CHECK_BOX: Check box
  • CREATED_TIME: Created datetime
  • CREATOR: Created by
  • DATE: Date
  • DATETIME: Date and time
  • DROP_DOWN: Drop-down
  • FILE: Attachment
  • LINK: Link
  • MODIFIER: Updated by
  • MULTI_LINE_TEXT: Text Area
  • MULTI_SELECT: Multi-choice
  • NUMBER: Number, or Look-up*
  • ORGANIZATION_SELECT: Department selection
  • RADIO_BUTTON: Radio button
  • RECORD_NUMBER: Record number
  • REFERENCE_TABLE: Related Records
  • RICH_TEXT: Rich text
  • SINGLE_LINE_TEXT: Text, or Look-up*
  • STATUS: Process management status
  • STATUS_ASSIGNEE: Assignee of the Process Management status
  • SUBTABLE: Table
  • TIME: Time
  • UPDATED_TIME: Updated datetime
  • USER_SELECT: User selection
*The type of the Look-up field will be the same type as the Key field it's looking up.
properties.{fieldcode}.noLabel Boolean The "Hide field name" option.
  • true: The field's name is hidden.
  • false: The field's name is displayed.
properties.{fieldcode}.required String The "Required field" option.
  • true: The field is a required field.
  • false: The field is not a required field.
properties.{fieldcode}.unique String The "Prohibit duplicate values" option.
  • true: Duplicate values are prohibited.
  • false: Duplicate values are not prohibited.
properties.{fieldcode}.maxValue String The maximum number of characters for the field.
properties.{fieldcode}.minValue String The minimum number of characters for the field.
properties.{fieldcode}.maxLength String The maximum number of digits for the field.
properties.{fieldcode}.minLength String The minimum number of digits for the field.
properties.{fieldcode}.defaultValue String or Array The default value.
An array will be returned for fields that can set multiple default values.
properties.{fieldcode}.defaultNowValue String The "Default to the record creation date" option.
  • true: The record creation date is used as the default value.
  • false: The record creation date is not used as the default value.
properties.{fieldcode}.options Object An object including data of the field's options.
properties.{fieldcode}.options.{optionname}.label String The name of the option.
properties.{fieldcode}.options.{optionname}.index String The display order (ascending) of the option, when listed with the other options.
properties.{fieldcode}.align String The layout of the options.
  • HORIZONTAL: The options are listed horizontally.
  • VERTICAL: The options are listed vertically.
properties.{fieldcode}.expression String The formula expression used in the field.
properties.{fieldcode}.hideExpression String The "Hide formula" settings for the field.
  • true: The formula is hidden.
  • false: The formula is displayed.
properties.{fieldcode}.digit String The "Use thousands separators" option.
  • true: Thousands separators are displayed for the number.
  • false: Thousands separators are not displayed for the number.
properties.{fieldcode}.thumbnailSize String The size of the image thumbnail in pixels.
properties.{fieldcode}.protocol String The Link type settings for the field.
  • WEB: URL
  • CALL: Telephone number
  • MAIL: E-mail address
properties.{fieldcode}.format String The display format for fields with calculations:
  • NUMBER: Number (1000)
  • NUMBER_DIGIT: Number with thousands separator (1,000)
  • DATETIME: Date & time (Aug 06, 2012 2:03 PM)
  • DATE: Date (Aug 06, 2012)
  • TIME: Time (2:03 PM)
  • HOUR_MINUTE: Hours & minutes (29 hours 47 minutes)
  • DAY_HOUR_MINUTE: Days & hours & minutes (1 day 5 hours 47 minutes)
properties.{fieldcode}.displayScale String The number of decimal places to display for the field.
properties.{fieldcode}.unit String The Currency settings of the field.
properties.{fieldcode}.unitPosition String The display position of the Currency.
  • BEFORE: The currency is displayed before the field value.
  • AFTER: The currency is displayed after the field value.
properties.{fieldcode}.entities Array An array listing the preset users for the field.
properties.{fieldcode}.entities[].code String The code of the user/group/department.
properties.{fieldcode}.entities[].type String The entity type.
  • USER: User
  • GROUP: Group
  • ORGANIZATION: Department
properties.{fieldcode}.referenceTable Object An object containing the settings of the Related Records field.
null is returned if there are no view permissions for the Datasource App.
properties.{fieldcode}.referenceTable.relatedApp Object An object containing data of the "Datasource App" setting.
properties.{fieldcode}.referenceTable.relatedApp.app String The App ID of the Datasource App.
properties.{fieldcode}.referenceTable.relatedApp.code String The App Code of the Datasource App.
If no App Code is set of the App, an empty string will be returned.
properties.{fieldcode}.referenceTable.condition Object An object containing data of the "Fetch Criteria" setting.
properties.{fieldcode}.referenceTable.condition.field String The field code of the field selected for "Field in this app".
properties.{fieldcode}.referenceTable.condition.relatedField String The field code of the field selected for "Field in datasource app".
properties.{fieldcode}.referenceTable.filterCond String The "Filter" setting, in a query format.
Check here for more information on query formats.
properties.{fieldcode}.referenceTable.displayFields Array A list of field codes of fields specified in the "Datasource App Fields to Display" setting.
properties.{fieldcode}.referenceTable.sort String The "Display Order" setting, in a query format.
Check here for more information on query formats.
properties.{fieldcode}.referenceTable.size String The "Max Records to Display at a Time" setting.
properties.{fieldcode}.lookup Object An object containing the settings of the Lookup field.
null is returned if there are no view permissions for the Datasource App.
properties.{fieldcode}.lookup.relatedApp Object An object containing data of the "Datasource App" setting.
properties.{fieldcode}.lookup.relatedApp.app String The App ID of the Datasource App.
properties.{fieldcode}.lookup.relatedApp.code String The App Code of the Datasource App.
An empty string is returned if no App Code is set.
properties.{fieldcode}.lookup.relatedKeyField String The field code for the field set in the "Key Field" setting.
properties.{fieldcode}.lookup.fieldMappings Array A list of data set for the "Field Mappings" setting.
If nothing is set, an empty string will be returned.
properties.{fieldcode}.lookup.fieldMappings[].field String The field code of the field set for the mapping endpoint.
properties.{fieldcode}.lookup.fieldMappings[].relatedField String The field code of the field set for the mapping source.
properties.{fieldcode}.lookup.lookupPickerFields Array A list of field codes of fields set for the "Fields Shown in Lookup Picker" setting.
If nothing is set, an empty string will be returned.
properties.{fieldcode}.lookup.filterCond String The default filter query for the "Filter" setting.
Check here for more information on query formats.
properties.{fieldcode}.lookup.sort String The default sort order for the "Filter" setting. Check here for more information on query formats.
properties.{fieldcode}.openGroup String The "Show fields in this group" option.
  • true: The Group field is displayed open by default.
  • false: The Group field is displayed closed by default.
properties.{fieldcode}.fields Object An object containing data of fields in a table.
The parameters of this object are the same as the properties parameter.
properties.{fieldcode}.enabled String The on/off settings of features.
Only returned for Process Management Status and Categories.
  • For Status fields:
    • true: The Process Management feature is enabled.
    • false: The Process Management feature is disabled.
  • For Category fields:
    • true: The Category feature is enabled
    • false: The Category feature is disabled
revision String The revision number of the App settings.

Sample Response

 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
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
{
  "properties": {
    "Text__single_line_1": {
      "type": "SINGLE_LINE_TEXT",
      "code": "Text__single_line_1",
      "label": "Text (single-line)",
      "noLabel": false,
      "required": true,
      "unique": true,
      "maxLength": "64",
      "minLength": "0",
      "defaultValue": "",
      "expression": "",
      "hideExpression": false
    },
    "Number": {
      "type": "NUMBER",
      "code": "Number",
      "label": "Number",
      "noLabel": true,
      "required": false,
      "unique": false,
      "maxValue": "64",
      "minValue": "0",
      "defaultValue": "12345",
      "expression": "",
      "digit": true,
      "displayScale": "",
      "unit": "$",
      "unitPosition": "BEFORE"
    },
    "Radio_Button": {
      "type": "RADIO_BUTTON",
      "code": "Radio_Button",
      "defaultValue": "sample2",
      "label": "Radio Button",
      "noLabel": false,
      "required": true,
      "options": {
        "sample1": {
          "label": "sample1",
          "index": 0
        },
        "sample2": {
          "label": "sample2",
          "index": 1
        },
        "sample3": {
          "label": "sample3",
          "index": 2
        }
      },
      "align": "horizontal"
    }
  },
  "revision": "2"
}