Add Form Fields

Adds fields to a form of an App.

This API updates the pre-live settings.
After using this API, use the Deploy App Settings API to deploy the settings to the live App.

MethodPOST
URLhttps://{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
Authentication Password Authentication, API Token Authentication, Session Authentication
Content-Typeapplication/json

Contents

Permissions

  • App Management Permissions are needed.

Request Parameters

Parameters that are ignored will not be updated.

Parameter Value Required Description
app Integer or String Yes The App ID.
properties Object Yes An object with data of the field settings.
properties.{fieldcode} Object An object with data of the field settings of the field specified in {fieldcode}.
To update a field code, state the current field code in {fieldcode}, and state the new field code in properties.{fieldcode}.code.
properties.{fieldcode}.label String The field name.
properties.{fieldcode}.code String The field code of the field.
Field codes have the following limitations:
  • The maximum character limit is 128
  • Duplicate field codes cannot exist
  • _ is the only symbol that can be used
  • Numbers cannot be used to start a field code
properties.{fieldcode}.type String Yes The field type.
  • GROUP: Group
  • GROUP_SELECT: Group selection
  • CALC: Calculated
  • CHECK_BOX: Check box
  • DATE: Date
  • DATETIME: Date and time
  • DROP_DOWN: Drop-down
  • FILE: Attachment
  • LINK: Link
  • MULTI_LINE_TEXT: Text Area
  • MULTI_SELECT: Multi-choice
  • NUMBER: Number
  • ORGANIZATION_SELECT: Department selection
  • RADIO_BUTTON: Radio button
  • RECORD_NUMBER: Record number
  • REFERENCE_TABLE: Related Records
  • RICH_TEXT: Rich text
  • SINGLE_LINE_TEXT: Text
  • SUBTABLE: Table
  • TIME: Time
  • USER_SELECT: User selection
For Lookup fields, specify either SINGLE_LINE_TEXT or NUMBER, depending on the type of the Key field it's looking up.
properties.{fieldcode}.noLabel Boolean or String The "Hide field name" option.
  • true: The field's name will be hidden.
  • false: The field's name will be displayed.
properties.{fieldcode}.required Boolean or String The "Required field" option.
  • true: The field will be a required field.
  • false: The field will not be a required field.
properties.{fieldcode}.unique Boolean or String The "Prohibit duplicate values" option.
  • true: Duplicate values will be prohibited.
  • false: Duplicate values will not be prohibited.
properties.{fieldcode}.maxValue Integer or String The maximum number of characters for the field.
properties.{fieldcode}.minValue Integer or String The minimum number of characters for the field.
properties.{fieldcode}.maxLength Integer or String The maximum number of digits for the field.
properties.{fieldcode}.minLength Integer or String The minimum number of digits for the field.
properties.{fieldcode}.defaultValue String or Array The default value.
For fields that can set multiple default values, specify the value as an array.
The defaultNowValue will take priority if it also specified.
For User/Group/Department fields, an array of objects that include code and type are required.
  • properties.{fieldcode}.defaultValue[].code
    State the code of the User/Group/Department, or the function "LOGINUSER()".Departments cannot be specified for Apps in Guest spaces.
  • properties.{fieldcode}.defaultValue[].type
     State the type of the default value
    • USER: User
    • GROUP: Group
    • ORGANIZATION: Department
    • FUNCTION: Function
properties.{fieldcode}.defaultNowValue Boolean or String The "Default to the record creation date" option.
  • true: The record creation date will be used as the default value.
  • false: The record creation date will not be used as the default value.
properties.{fieldcode}.options Object An object including data of the field's options.
properties.{fieldcode}.options.{optionname} Object An object with data of the settings of the options.
Specify the current option names for this parameter. Options that are not specified will be deleted.
If a new option is specified for this parameter, it will be treated as a new option.
properties.{fieldcode}.options.{optionname}.label String The display name of the option.
If a new option is specified for properties.{fieldcode}.options.{optionname}, specify the same value for this parameter.
properties.{fieldcode}.options.{optionname}.index Integer or String Conditional The display order (ascending) of the option, when listed with the other options.
Required, if setting the properties.{fieldcode}.options parameter.
properties.{fieldcode}.align String The layout of the options.
  • HORIZONTAL: The options will be listed horizontally.
  • VERTICAL: The options will be listed vertically.
properties.{fieldcode}.expression String The formula expression used in the field.
properties.{fieldcode}.hideExpression Boolean or String The "Hide formula" settings for the field.
  • true: The formula will be hidden.
  • false: The formula will be displayed.
properties.{fieldcode}.digit Boolean or String The "Use thousands separators" option.
  • true: Thousands separators will be displayed for the number.
  • false: Thousands separators will not be displayed for the number.
properties.{fieldcode}.thumbnailSize Integer or String The size of the image thumbnail in pixels.
Specify one of the following: 50, 150, 250, 500
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 Integer or 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 will be displayed before the field value.
  • AFTER: The currency will be displayed after the field value.
properties.{fieldcode}.entities Array of Objects An array listing the preset users for the field.
properties.{fieldcode}.entities[].code String Conditional The code of the user/group/department.Required, if the entities parameter is specified.
properties.{fieldcode}.entities[].type String Conditional The entity type.
  • USER: User
  • GROUP: Group
  • ORGANIZATION: Department
Required, if the entities parameter is specified.
properties.{fieldcode}.referenceTable Object An object containing the settings of the Related Records field.
properties.{fieldcode}.referenceTable.relatedApp Object An object containing data of the "Datasource App" setting.
If this parameter is specified, all settings for this Related Records field except for the "Datasource App" setting will return to the default settings.
properties.{fieldcode}.referenceTable.relatedApp.app Integer or String Conditional The App ID of the Datasource App. If the relatedApp parameter is specified, either this parameter or properties.{fieldcode}.referenceTable.relatedApp.code will be required.
If both parameters are set, properties.{fieldcode}.referenceTable.relatedApp.code will take priority.
properties.{fieldcode}.referenceTable.relatedApp.code String Conditional The App Code of the Datasource App.
If the relatedApp parameter is specified, either this parameter or properties.{fieldcode}.referenceTable.relatedApp.app will be required.
If both parameters are set, properties.{fieldcode}.referenceTable.relatedApp.code will take priority.
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 of Strings 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 Integer or String The "Max Records to Display at a Time" setting.
Specify one of the following: 1, 3, 5, 10, 20, 30, 40, 50
properties.{fieldcode}.lookup Object An object containing the settings of the Lookup field.
properties.{fieldcode}.lookup.relatedApp Object Conditional An object containing the settings of the related App of the Lookup field. Required, if setting the lookup parameter.
properties.{fieldcode}.lookup.relatedApp.app Integer or String Conditional The App ID of the related App of the Lookup field. Either this parameter or the lookup.relatedApp.code parameter is required if setting the lookup parameter. If both parameters are set, the lookup.relatedApp.code parameter takes priority.
properties.{fieldcode}.lookup.relatedApp.code String Conditional The App Code of the related App of the Lookup field. Either this parameter or the lookup.relatedApp.app parameter is required if setting the lookup parameter. If both parameters are set, this parameter takes priority.
properties.{fieldcode}.lookup.relatedKeyField String Conditional The field code of the Lookup field. Required, if setting the lookup parameter.
properties.{fieldcode}.lookup.fieldMappings Array of Objects A list of data set for the "Field Mappings" setting.
properties.{fieldcode}.lookup.fieldMappings[].field String Conditional The field code of the field set for the mapping endpoint. Required, if setting the lookup parameter.
properties.{fieldcode}.lookup.fieldMappings[].relatedField String Conditional The field code of the field set for the mapping source.
Required, if setting the lookup parameter.
properties.{fieldcode}.lookup.lookupPickerFields Array of Strings A list of field codes of fields set for the "Fields Shown in Lookup Picker" setting.
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 Boolean or String The "Show fields in this group" option.
  • true: The Group field will be displayed open by default.
  • false: The Group field will be 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.
revision Integer or String Specify the revision number of the settings that will be deployed.
The request will fail if the revision number is not the latest revision.
The revision will not be checked if this parameter is ignored, or -1 is specified.

Sample Request

JavaScript (using Kintone REST API Request)

 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
var body = {
  'app': 1,
  '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',
      'digit': true,
      'displayScale': '',
      'expression': '',
      'unit': '$',
      'unitPosition': 'BEFORE'
    }
  }
};

kintone.api(kintone.api.url('/k/v1/preview/app/form/fields.json', true), 'POST', 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
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
var body = {
  'app': 1,
  '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',
      'digit': true,
      'displayScale': '',
      'expression': '',
      'unit': '$',
      'unitPosition': 'BEFORE'
    }
  },
  // CSRF TOKEN: used for all APIs that have an HTTP method of POST, PUT and DELETE on Kintone.
  '__REQUEST_TOKEN__': kintone.getRequestToken()
};

var url = 'https://{subdomain}.kintone.com/k/v1/preview/app/form/fields.json';
var xhr = new XMLHttpRequest();
xhr.open('POST', url);
xhr.setRequestHeader('X-Requested-With', 'XMLHttpRequest');
xhr.setRequestHeader('Content-Type', 'application/json');
xhr.onload = function() {
  if (xhr.status === 200) {
    // success
    console.log(JSON.parse(xhr.responseText));
  } else {
    // error
    console.log(JSON.parse(xhr.responseText));
  }
};
xhr.send(JSON.stringify(body));

Response Parameters

Parameter Type Description
revision String The revision number of the App settings.

Sample Response

1
2
3
{
  "revision": "1"
}

Limitations

The field codes of the following fields cannot be added:

  • Label
  • Blank space
  • Border
  • Status
  • Assignee
  • Category