Update Form Fields
Updates the field settings of fields in 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
Method | PUT |
---|---|
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 , API Token Authentication , Session Authentication |
Content-Type | application/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
|
|
properties.{fieldcode}.type | String | Yes | The field type.
|
properties.{fieldcode}.noLabel | Boolean or String | The "Hide field name" option.
|
|
properties.{fieldcode}.required | Boolean or String | The "Required field" option.
|
|
properties.{fieldcode}.unique | Boolean or String | The "Prohibit duplicate values" option.
|
|
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}.defaultNowValue | Boolean or String | The "Default to the record creation date" option.
|
|
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.
|
|
properties.{fieldcode}.expression | String | The formula expression used in the field. | |
properties.{fieldcode}.hideExpression | Boolean or String | The "Hide formula" settings for the field.
|
|
properties.{fieldcode}.digit | Boolean or String | The "Use thousands separators" option.
|
|
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.
|
|
properties.{fieldcode}.format | String | The display format for fields with calculations:
|
|
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.
|
|
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.
|
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. For more data on query formats refer to the following document: Query String |
|
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. 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 |
|
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. 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. 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.
|
|
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 Requests
|
|
|
|
|
|
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