Add Form Fields

Last Updated:
Follow
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.
Method POST
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
Authentication Password Authentication
Content-Type application/json

Permissions

  • App Management Permissions are needed.
  • API Tokens cannot be used with this API.

Request Parameters

Parameter Value Required Description
app Integer Yes The App ID.
properties Object Yes An object with data of the field settings.
properties.{fieldcode} Object Yes An object with data of fields that will be added.
Specify the field code of the field for {fieldcode}.
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}.label String Conditional The field name.
Ignore this parameter for tables.
properties.{fieldcode}.code String Yes The field code of the field.
Specify the same value used for the properties.{fieldcode} parameter.
properties.{fieldcode}.type String Yes The field type.
  • 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
  • RADIO_BUTTON: Radio button
  • 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   The "Hide field name" option.
  • true: The field's name will be hidden.
  • false: (default) The field's name will be displayed.
properties.{fieldcode}.required Boolean   The "Required field" option.
  • true: The field will be a required field.
  • false: (default) The field will not be a required field.
properties.{fieldcode}.unique Boolean   The "Prohibit duplicate values" option.
  • true: Duplicate values will be prohibited.
  • false: (default) Duplicate values will not be prohibited.
properties.{fieldcode}.maxValue Integer   The maximum value for the field.
properties.{fieldcode}.minValue Integer   The minimum value for the field.
properties.{fieldcode}.maxLength Integer   The maximum number of characters for the field.
properties.{fieldcode}.minLength Integer   The minimum number of characters 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.
properties.{fieldcode}.defaultNowValue String   The "Default to the record creation date" option.
  • true: The record creation date will be used as the default value.
  • false: (default) The record creation date will not be used as the default value.
properties.{fieldcode}.options Object Conditional An object including data of the field's options. Required for fields that have multiple options, such as Radio button fields.
properties.{fieldcode}.options.{optionname} Object Conditional An object with data of the settings of the options.
Specify the option name for this parameter.
Required, if the options parameter is specified.
properties.{fieldcode}.options.{optionname}.label String Conditional The display name of the option. Specify the same value used for the properties.{fieldcode}.options.{optionname} parameter.
Required, if the options parameter is specified.
properties.{fieldcode}.options.{optionname}.index Integer Conditional The display order (ascending) of the option, when listed with the other options.
Required, if the options parameter is specified.
properties.{fieldcode}.align String   The layout of the options.
  • HORIZONTAL: (default) The options will be listed horizontally.
  • VERTICAL: The options will be listed vertically.
properties.{fieldcode}.expression String Conditional The formula expression used in the field.
Required, for Calculated fields.
properties.{fieldcode}.hideExpression Boolean   The "Hide formula" settings for the field.
  • true: The formula will be hidden.
  • false: (default) The formula will be displayed.
properties.{fieldcode}.digit Boolean   The "Use thousands separators" option.
  • true: Thousands separators will be displayed for the number.
  • false: (default) Thousands separators will not be displayed for the number.
properties.{fieldcode}.thumbnailSize Integer   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, for Link fields.
  • 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   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: (default) The currency will be displayed before the field value.
  • AFTER: The currency will be displayed after the field value.
properties.{fieldcode}.entities Array   An array listing the preset users for the User/Group/Department selection field.
properties.{fieldcode}.entities[].code String Conditional The code of the user/group/department or the function "LOGINUSER()".
Departments cannot be specified for Apps in Guest spaces.
Required, if the entities parameter is specified.
properties.{fieldcode}.entities[].type String Conditional The entity type.

  • USER: User
  • GROUP: Group
  • ORGANIZATION: Department
  • FUNCTION: Function
Required, if the entities parameter is specified.
properties.{fieldcode}.referenceTable Object Conditional An object containing the settings of the Related Records field.
Required for Related Record fields.
properties.{fieldcode}.referenceTable.relatedApp Object Conditional An object containing data of the "Datasource App" setting.
Required, if the referenceTable parameter is specified.
properties.{fieldcode}.referenceTable.relatedApp.app Integer 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 the referenceTable parameter is specified.
properties.{fieldcode}.referenceTable.condition.field String Conditional The field code of the field selected for "Field in this app".
Required, if the referenceTable parameter is specified.
properties.{fieldcode}.referenceTable.condition.relatedField String Conditional The field code of the field selected for "Field in datasource app".
Required, if the referenceTable parameter is specified.
properties.{fieldcode}.referenceTable.fliterCond String   The "Filter" setting, in a query format.
Check here for more information on query formats.
properties.{fieldcode}.referenceTable.displayFields Array Conditional A list of field codes of fields specified in the "Datasource App Fields to Display" setting.
Required, if the referenceTable parameter is specified.
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   The "Max Records to Display at a Time" setting.
Specify one of the following: 5, 10, 20, 30
Default is 5.
properties.{fieldcode}.lookup Object   An object containing the settings of the Lookup field.
Required for Lookup fields.
properties.{fieldcode}.lookup.relatedApp Object Conditional An object with data of the "Datasource App" settings.
Required for Lookup fields.
properties.{fieldcode}.lookup.relatedApp.app Integer Conditional The App ID of the Datasource App.
If the lookup parameter is specified, either this parameter or the properties.{fieldcode}.lookup.relatedApp.code parameter will be required.
If both parameters are set, properties.{fieldcode}.lookup.relatedApp.code will take priority.
properties.{fieldcode}.lookup.relatedApp.code String Conditional The App Code of the Datasource App.
If the lookup parameter is specified, either this parameter or the properties.{fieldcode}.lookup.relatedApp.app parameter will be required.
If both parameters are set, properties.{fieldcode}.lookup.relatedApp.code will take priority.
properties.{fieldcode}.lookup.relatedKeyField String Conditional The field code of the field to specify for the "Key Field" setting.
Required for Lookup fields.
properties.{fieldcode}.lookup.fieldMappings Array   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 specifying the lookup.fieldMappings parameter.
properties.{fieldcode}.lookup.fieldMappings[].relatedField String Conditional The field code of the field set for the mapping source.
Required, if specifying the lookup.fieldMappings parameter.
properties.{fieldcode}.lookup.lookupPickerFields Array   A list of field codes of fields to 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   The "Show fields in this group" option.
  • true: The Group field will be displayed open by default.
  • false: (default) 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. Required for tables fields.
revision Integer   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)

XMLHttpRequest

Response Parameters

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

Sample Response

Limitations

The following fields cannot be added:

  • Label
  • Blank space
  • Border
  • Status
  • Assignee
  • Category
Was this article helpful?
0 out of 0 found this helpful
Do you have any questions or issues related to this article?
Please share your views with us in the Community forums!