Update Form Layout

Updates the field layout info of a form in 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.

MethodPUT
URLhttps://{subdomain}.kintone.com/k/v1/preview/app/form/layout.json
URL(guest space)https://{subdomain}.kintone.com/k/guest/{SpaceID}/v1/preview/app/form/layout.json
Authentication Password Authentication, API Token Authentication, Session Authentication
Content-Typeapplication/json

Contents

Permissions

  • App Management Permissions are needed.

Request Parameters

Parameters that are ignored will not be updated
All fields in the form must be specified in the request.

Parameter Value Required Description
app Integer Yes The App ID.
layout Array Yes A list of field layouts for each row.
layout[].type String Yes The type of row.
  • ROW: A normal row of fields.
  • SUBTABLE: A Table.
  • GROUP: A Group field.
layout[].code String Conditional The field code of the Table or Group field. Ignore, if the row type is not a Table or a Group.
layout[].fields Array The list of fields in the row.
layout[].fields[].type String Yes The type of field.
  • CALC: Calculated
  • CATEGORY: Category
  • CHECK_BOX: Check box
  • CREATED_TIME: Created datetime
  • CREATOR: Created by
  • DATE: Date
  • DATETIME: Date and time
  • DROP_DOWN: Drop-down
  • FILE: Attachment
  • HR: Border
  • LABEL: Label
  • 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
  • SPACER: Blank space
  • 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.
layout[].fields[].code String Conditional The field code of the field. Ignore, if the field is a Label, Blank space or a Border.
layout[].fields[].label String The text to set into the Label field.
Only specify for Label fields.
layout[].fields[].elementId String The element ID to set to the Blank space field. Only specify for Blank space fields.
layout[].fields[].size Object An object with data of the field's size.
Depending on how the field is placed, the field may not become the size that you specified.
layout[].fields[].size.width Integer The width of the field in pixels.
The width can be set for the following fields:
  • Attachment
  • Blank space
  • Border
  • Calculated
  • Check box
  • Created by
  • Created datetime
  • Date and time
  • Date
  • Drop-down
  • Label
  • Link
  • Lookup
  • Multi-choice
  • Number
  • Radio button
  • Record number
  • Rich text
  • Text Area
  • Text
  • Time
  • Updated by
  • Updated datetime
  • User selection
layout[].fields[].size.height Integer The height of the field in pixels, including the height of the field name.
Only Blank space fields can use this parameter.
layout[].fields[].size.innerHeight Integer The height of the field in pixels, excluding the height of the field name.
Only the following fields can use this parameter:
  • Text Area
  • Rich text
layout[].layout Array A list of field layouts for each row inside a Group field.
The parameters for this are the same for the layout property.
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)

 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
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
var body = {
  'app': 1,
  'layout': [
    {
      'type': 'ROW',
      'fields': [
        {
          'type': 'SINGLE_LINE_TEXT',
          'code': 'Text__single_line_',
          'size': {
            'width': '200'
          }
        }
      ]
    },
    {
      'type': 'SUBTABLE',
      'code': 'Table',
      'fields': [
        {
          'type': 'SINGLE_LINE_TEXT',
          'code': 'Text2__single_line_',
          'size': {
            'width': '193'
          }
        },
        {
          'type': 'MULTI_LINE_TEXT',
          'code': 'Text_Box__multi_line_',
          'size': {
            'width': '315',
            'innerHeight': '125'
          }
        }
      ]
    },
    {
      'type': 'ROW',
      'fields': [
        {
          'type': 'NUMBER',
          'code': 'Number',
          'size': {
            'width': '193'
          }
        }
      ]
    },
    {
      'type': 'ROW',
      'fields': [
        {
          'type': 'RECORD_NUMBER',
          'code': 'Record_number',
          'size': {
            'width': '141'
          }
        },
        {
          'type': 'CREATOR',
          'code': 'Created_by',
          'size': {
            'width': '136'
          }
        }
      ]
    }
  ]
};

kintone.api(kintone.api.url('/k/v1/preview/app/form/layout.json', true), 'PUT', 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
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
var body = {
  'app': 1,
  'layout': [
    {
      'type': 'ROW',
      'fields': [
        {
          'type': 'SINGLE_LINE_TEXT',
          'code': 'Text__single_line_',
          'size': {
            'width': '200'
          }
        }
      ]
    },
    {
      'type': 'SUBTABLE',
      'code': 'Table',
      'fields': [
        {
          'type': 'SINGLE_LINE_TEXT',
          'code': 'Text2__single_line_',
          'size': {
            'width': '193'
          }
        },
        {
          'type': 'MULTI_LINE_TEXT',
          'code': 'Text_Box__multi_line_',
          'size': {
            'width': '315',
            'innerHeight': '125'
          }
        }
      ]
    },
    {
      'type': 'ROW',
      'fields': [
        {
          'type': 'NUMBER',
          'code': 'Number',
          'size': {
            'width': '193'
          }
        }
      ]
    },
    {
      'type': 'ROW',
      'fields': [
        {
          'type': 'RECORD_NUMBER',
          'code': 'Record_number',
          'size': {
            'width': '141'
          }
        },
        {
          'type': 'CREATOR',
          'code': 'Created_by',
          'size': {
            'width': '136'
          }
        }
      ]
    }
  ],
  // 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/layout.json';
var xhr = new XMLHttpRequest();
xhr.open('PUT', 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": "4"
}