Add Form Fields

Adds fields to a form of an App.

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

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

  • Permission to Manage App is 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 Yes 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.
For the characters that can be used for field codes, refer to the following document:
Valid characters (External link)
properties.{fieldcode}.label String Yes The field name.
properties.{fieldcode}.code String Yes 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 depending on the Key field type 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.
If ignored, false will be set.
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.
If ignored, false will be set.
properties.{fieldcode}.unique Boolean or String The Prohibit duplicate values option.
  • true: Duplicate values will be prohibited.
  • false: Duplicate values will not be prohibited.
If ignored, false will be set.
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 is also specified.
For the User selection, Group selection, and Department selection fields, an array of objects that include code and type is required.
properties.{fieldcode}.defaultValue[].type String Conditional The type of the default value of the User selection, Group selection, or Department selection field.
Required if setting the defaultValue parameter.
  • USER: User
  • GROUP: Group
  • ORGANIZATION: Department
  • FUNCTION: Function
properties.{fieldcode}.defaultValue[].code String Conditional The code for the default value of User selection, Group selection, or Department selection field.
Required if setting the defaultValue parameter.
  • For User selection field, one of the following values can be specified:
    • User code (log-in name)
    • Group code
    • Department code
    • Function name LOGINUSER()
    Departments cannot be specified for Apps in Guest spaces.
  • For Group selection field, a Group code can be specified.
  • For Department selection field, one of the following values can be specified:
    • Department code
    • Function name PRIMARY_ORGANIZATION()
Deleted or inactive User/Group/Department cannot be specified.
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.
If ignored, false will be set.
properties.{fieldcode}.options Object Conditional An object including data of the field's options.
Required for fields that allow selections, such as Radio button.
properties.{fieldcode}.options.{optionname} Object Conditional 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.
Required if setting the properties.{fieldcode}.options parameter.
If a new option is specified for this parameter, it will be treated as a new option.
properties.{fieldcode}.options.{optionname}.label String Conditional The display name of the option.
Specify the same value as {optionname}.
Required if setting the properties.{fieldcode}.options 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.
If ignored, HORIZONTAL will be set.
properties.{fieldcode}.expression String Conditional The formula expression used in the field.
Required in the Calculated 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.
If ignored, false will be set.
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.
If ignored, false will be set.
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 Conditional The Link type settings for the field.
Required in the Link field.
  • WEB: URL
  • CALL: Telephone number
  • MAIL: E-mail address
properties.{fieldcode}.format String The display format for fields with calculations:
  • NUMBER: Number (e.g.: 1000)
  • NUMBER_DIGIT: Number with thousands separator (e.g.: 1,000)
  • DATETIME: Date & time (e.g.: Aug 06, 2012 2:03 PM)
  • DATE: Date (e.g.: Aug 06, 2012)
  • TIME: Time (e.g.: 2:03 PM)
  • HOUR_MINUTE: Hours & minutes (e.g.: 29 hours 47 minutes)
  • DAY_HOUR_MINUTE: Days & hours & minutes (e.g.: 1 day 5 hours 47 minutes)
If ignored, NUMBER will be set.
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.
If ignored, BEFORE will be set.
properties.{fieldcode}.entities Array of Objects An array listing the preset users for the User selection, Group selection, and Department selection field.
properties.{fieldcode}.entities[].code String Conditional The code of the User/Group/Department.
Required if setting the entities.
  • For User selection field, one of the following values can be specified:
    • User code (log-in name)
    • Group code
    • Department code
    Departments cannot be specified for Apps in Guest spaces.
  • For Group selection field, a Group code can be specified.
  • For Department selection field, a Department code can be specified.
Deleted or inactive User/Group/Department cannot be specified.
properties.{fieldcode}.entities[].type String Conditional The entity type.
  • USER: User
  • GROUP: Group
  • ORGANIZATION: Department

Required if setting the entities parameter.
properties.{fieldcode}.referenceTable Object Conditional An object containing the settings of the Related Records field.
Required when adding a Related Records field.
properties.{fieldcode}.referenceTable.relatedApp Object Conditional 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.
Required if setting the referenceTable parameter.
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 Conditional An object containing data of the Fetch Criteria setting.
Required if setting the referenceTable parameter.
properties.{fieldcode}.referenceTable.condition.field String Conditional The field code of the field selected for Field in this app.
Required if setting the referenceTable parameter.
properties.{fieldcode}.referenceTable.condition.relatedField String Conditional The field code of the field selected for Field in datasource app.
Required if setting the referenceTable parameter.
properties.{fieldcode}.referenceTable.filterCond String The Filter setting, in a query format.
For more data on query formats refer to the following document:
Query String
properties.{fieldcode}.referenceTable.displayFields Array of Strings Conditional A list of field codes of fields specified in the Datasource App Fields to Display setting.
Required if setting the referenceTable parameter.
properties.{fieldcode}.referenceTable.sort String Conditional The Display Order setting, in a query format.
For more data on query formats refer to the following document:
Query String
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
If ignored, 5 will be set.
properties.{fieldcode}.lookup Object An object containing the settings of the Lookup field.
Required if adding a 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.fieldMappings[] parameter.
properties.{fieldcode}.lookup.fieldMappings[].relatedField String Conditional The field code of the field set for the mapping source.
Required if setting the lookup.fieldMappings[] 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.
Specify in query format. For more data on query formats refer to the following document:
Query String
properties.{fieldcode}.lookup.sort String The default sort order for the Filter setting.
Specify in query format. For more data on query formats refer to the following document:
Query String
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.
If ignored, false will be set.
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.
Required when adding a table.
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

 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
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:

  • Status
  • Assignee
  • Category