Skip to main content
Use these endpoints to read and modify the fields and layout of an app’s form. All requests require authentication.
Preview vs. live endpointsEndpoints under /k/v1/preview/... operate on the app’s draft settings — changes are not visible to end users until you call Deploy App Settings. Endpoints under /k/v1/app/... (without preview) return the currently live settings.After making changes via a preview endpoint, remember to deploy the app.

​
Form fields

Returns field definitions for the live version of an app’s form. To retrieve draft (pre-deployment) fields, use /k/v1/preview/app/form/fields.json instead.

​
Query parameters

ParameterTypeRequiredDescription
appIntegerYesThe app ID.
langStringNoLanguage code for field labels: en, zh, ja, user, or default. Defaults to default.

​
Response properties

PropertyTypeDescription
propertiesObjectA map of field codes to field definition objects.
revisionStringThe current revision number of the app settings.
Each field definition object contains at minimum:
PropertyTypeDescription
typeStringThe field type (e.g., SINGLE_LINE_TEXT, NUMBER, DATE).
codeStringThe unique field code.
labelStringThe field label displayed in the form.
noLabelBooleanWhether the field label is hidden.
requiredBooleanWhether the field is required.

​
Examples

curl -X GET 'https://{subdomain}.kintone.com/k/v1/app/form/fields.json?app=1' \
  -H 'X-Cybozu-Authorization: {AuthorizationCode}'
Sample response
{
  "properties": {
    "Text_field": {
      "type": "SINGLE_LINE_TEXT",
      "code": "Text_field",
      "label": "Text",
      "noLabel": false,
      "required": true,
      "unique": false,
      "maxLength": "64",
      "minLength": "0",
      "defaultValue": ""
    }
  },
  "revision": "2"
}
Adds one or more fields to the draft version of the app form. Deploy the app to make changes live.

​
Request body

ParameterTypeRequiredDescription
appIntegerYesThe app ID.
propertiesObjectYesA map of field codes to field definition objects.
revisionIntegerNoThe expected revision number. Use -1 to skip the check.

​
Response properties

PropertyTypeDescription
revisionStringThe new revision number after the change.

​
Examples

curl -X POST 'https://{subdomain}.kintone.com/k/v1/preview/app/form/fields.json' \
  -H 'X-Cybozu-Authorization: {AuthorizationCode}' \
  -H 'Content-Type: application/json' \
  -d '{
    "app": 1,
    "properties": {
      "Customer_name": {
        "type": "SINGLE_LINE_TEXT",
        "code": "Customer_name",
        "label": "Customer name",
        "required": true
      }
    }
  }'
Sample response
{
  "revision": "3"
}
Updates properties of existing fields in the draft version of the app form. You cannot change a field’s type or code. Deploy the app to make changes live.

​
Request body

ParameterTypeRequiredDescription
appIntegerYesThe app ID.
propertiesObjectYesA map of field codes to updated field definition properties.
revisionIntegerNoThe expected revision number. Use -1 to skip the check.

​
Response properties

PropertyTypeDescription
revisionStringThe new revision number after the change.

​
Examples

curl -X PUT 'https://{subdomain}.kintone.com/k/v1/preview/app/form/fields.json' \
  -H 'X-Cybozu-Authorization: {AuthorizationCode}' \
  -H 'Content-Type: application/json' \
  -d '{
    "app": 1,
    "properties": {
      "Customer_name": {
        "label": "Full name",
        "required": false
      }
    }
  }'
Sample response
{
  "revision": "4"
}
Deletes one or more fields from the draft version of the app form. Deploy the app to make changes live.
Deleting a field also deletes all data stored in that field for every record. This cannot be undone after deployment.

​
Request body

ParameterTypeRequiredDescription
appIntegerYesThe app ID.
fieldsArray of stringsYesThe field codes to delete.
revisionIntegerNoThe expected revision number. Use -1 to skip the check.

​
Response properties

PropertyTypeDescription
revisionStringThe new revision number after the change.

​
Examples

curl -X DELETE 'https://{subdomain}.kintone.com/k/v1/preview/app/form/fields.json' \
  -H 'X-Cybozu-Authorization: {AuthorizationCode}' \
  -H 'Content-Type: application/json' \
  -d '{
    "app": 1,
    "fields": ["Customer_name"]
  }'
Sample response
{
  "revision": "5"
}

​
Form layout

Returns the layout information (row and field arrangement) for the live version of the app form. To retrieve the draft layout, use /k/v1/preview/app/form/layout.json.

​
Query parameters

ParameterTypeRequiredDescription
appIntegerYesThe app ID.

​
Response properties

PropertyTypeDescription
layoutArrayList of layout row objects.
layout[].typeStringRow type: ROW, SUBTABLE, or GROUP.
layout[].fieldsArrayFields in the row, each with type, code, size (width/height).
revisionStringThe current revision number of the app settings.

​
Examples

curl -X GET 'https://{subdomain}.kintone.com/k/v1/app/form/layout.json?app=1' \
  -H 'X-Cybozu-Authorization: {AuthorizationCode}'
Sample response
{
  "layout": [
    {
      "type": "ROW",
      "fields": [
        {
          "type": "SINGLE_LINE_TEXT",
          "code": "Customer_name",
          "size": { "width": "200" }
        }
      ]
    }
  ],
  "revision": "2"
}
Updates the layout of the app form in draft. Deploy the app to make changes live.

​
Request body

ParameterTypeRequiredDescription
appIntegerYesThe app ID.
layoutArrayYesThe new layout. Each element represents a row with a type and a fields array.
revisionIntegerNoThe expected revision number. Use -1 to skip the check.

​
Response properties

PropertyTypeDescription
revisionStringThe new revision number after the change.

​
Examples

curl -X PUT 'https://{subdomain}.kintone.com/k/v1/preview/app/form/layout.json' \
  -H 'X-Cybozu-Authorization: {AuthorizationCode}' \
  -H 'Content-Type: application/json' \
  -d '{
    "app": 1,
    "layout": [
      {
        "type": "ROW",
        "fields": [
          {
            "type": "SINGLE_LINE_TEXT",
            "code": "Customer_name",
            "size": { "width": "200" }
          }
        ]
      }
    ]
  }'
Sample response
{
  "revision": "3"
}

​
Deprecated

This endpoint is deprecated. Use Get Form Fields and Get Form Layout instead.
Returns both field definitions and layout information combined. A preview version is available at /k/v1/preview/form.json.

​
Query parameters

ParameterTypeRequiredDescription
appIntegerYesThe app ID.

Build docs developers (and LLMs) love

Get started for freeTalk to us