Join the program

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 API Token Authentication , Password Authentication
Content-Type application/json

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.
  • CALC: Calculated
  • 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
  • RADIO_BUTTON: Radio button
  • RECORD_NUMBER: Record number
  • REFERENCE_TABLE: Related Records
  • RICH_TEXT: Rich text
  • SINGLE_LINE_TEXT: Text
  • SUBTABLE: Table
  • TIME: Time
  • UPDATED_TIME: Updated datetime
  • 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.fliterCond 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: 5, 10, 20, 30, 40, 50
properties.{fieldcode}.lookup Object   An object containing the settings of the Lookup field.
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)

XMLHttpRequest

Response Parameters

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

Sample Response

Limitations

The field codes of the following fields cannot be updated

  • 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!