API Docs

Update Records

Updates details of multiple records in an App, by specifying their record numbers, or their unique keys. If the upsert parameter is set to true, it also adds new records to the App.

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

Contents

Permissions

  • Permission to update records of the App is needed.
  • Permission to update fields that are included in the request parameters are needed.
  • Permission to add records to the App is needed if the upsert parameter is set to true.

Request Parameters

PARAMETER VALUE REQUIRED DESCRIPTION
app Integer or String Yes The App ID.
upsert Boolean Optional A mode where adding and updating records can be processed at the same time.
records Array of Objects Yes Holds an array of objects that include id/updateKey, revision and record objects.
records[].id Integer or String Conditionally Required The Record ID of the record to be updated. Required, if updateKey will not be specified.
If upsert is set to true:
  • If the record exists, the record will be updated
  • If the record does not exist, it will be added as a new record. The specified ID will be ignored, and a new ID will be set to the new record.
records[].updateKey Object Conditionally Required The unique key of the record to be updated. Required, if id will not be specified. To specify this field, the field must have the Prohibit duplicate values option turned on.
If upsert is set to true:
  • If the record exists, the record will be updated
  • If the record does not exist, it will be added as a new record
records[].updateKey.field String Conditionally Required The field code of the unique key. Required, if updateKey will be specified.
records[].updateKey.value Integer or String Conditionally Required The value of the unique key. Required, if updateKey will be specified.
records[].revision Integer or String Optional The expected revision number. If the value does not match, an error will occur and all records will not be updated. If the value is not specified or is -1, the revision number will not be checked.
records[].record Object Optional Field codes and values are specified in this object. If ignored, the record will not be updated. For more information on field types, refer to the following article:
Field Types

Sample Request (id)

JavaScript using kintone.api() 

 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

var body = {
  'app': 1,
  'upsert': true,
  'records': [
    {
      'id': 1,
      'record': {
        'Text': {
          'value': 'Silver plates'
        }
      }
    },
    {
      'id': 2,
      'record': {
        'Text': {
          'value': 'The quick brown fox.'
        }
      }
    }
  ]
};

kintone.api(kintone.api.url('/k/v1/records.json', true), 'PUT', body, function(resp) {
  // success
  console.log(resp);
}, function(error) {
  // error
  console.log(error);
});

curl Sample 

 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

$ curl -X PUT 'https://{subdomain}.kintone.com/k/v1/records.json' \
-H 'X-Cybozu-API-Token: {APIToken}' \
-H 'Content-Type: application/json' \
-d '{
    "app": 1,
    "upsert": true,
    "records": [
        {
            "id": 1,
            "record": {
                "Text": {
                    "value": "Silver plates"
                }
            }
        },
        {
            "id": 2,
            "record": {
                "Text": {
                    "value": "The quick brown fox."
                }
            }
        }
    ]
}'

Sample Request (updateKey)

JavaScript using kintone.api() with updateKey 

 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

var body = {
  'app': 1,
  'upsert': true,
  'records': [
    {
      'updateKey': {
        'field': 'unique_key',
        'value': 'unique_code'
      },
      'record': {
        'Text': {
          'value': 'Silver plates'
        }
      }
    },
    {
      'updateKey': {
        'field': 'unique_key',
        'value': 'unique_code2'
      },
      'record': {
        'Text': {
          'value': 'The quick brown fox.'
        }
      }
    }
  ]
};

kintone.api(kintone.api.url('/k/v1/records.json', true), 'PUT', body, function(resp) {
  // success
  console.log(resp);
}, function(error) {
  // error
  console.log(error);
});

curl Sample 

 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

$ curl -X PUT 'https://{subdomain}.kintone.com/k/v1/records.json' \
-H 'X-Cybozu-API-Token: {APIToken}' \
-H 'Content-Type: application/json' \
-d '{
    "app": 1,
    "upsert": true,
    "records": [
        {
            "updateKey": {
                "field": "unique_key",
                "value": "CODE123"
            },
            "record": {
                "Text": {
                    "value": "Silver plates"
                }
            }
        },
        {
            "updateKey": {
                "field": "unique_key",
                "value": "CODE456"
            },
            "record": {
                "Text": {
                    "value": "The quick brown fox."
                }
            }
        }
    ]
}'

Response Parameters

Parameter Type Description
records[].ids Array of Strings The Record IDs of the updated/created Records.
records[].revisions Array of Strings The revision numbers of the Records.
records[].operation String The operation processed on the record. This parameter is only responded if upsert is set to true.
  • INSERT: Record added
  • UPDATE: Record updated

Sample Response

When upsert is set to false:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14

{
  "records": [
    {
      // First data
      "id": "1",
      "revision": "5"
    },
    {
      // Second data
      "id": "2",
      "revision": "2"
    }
  ]
}

When upsert is set to true:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14

{
  "records": [
    {
      "id": "3",
      "operation": "UPDATE",
      "revision": "5"
    },
    {
      "id": "4",
      "operation": "INSERT",
      "revision": "5"
    }
  ]
}

Attachment fields and Tables

Updating and deleting files on attachment fields

If you want to add new file to an attachment field that already has several files attached to it, you will need to specify the fileKeys of those files in the request. You cannot update a specific attachment file.
If a fileKey is not specified in the request, the files will be deleted.

Updating tables

If data of the tables are not included in the request, the table data will stay as it is.
If table data is included in the request, take note of the following:

  • All fields inside the table that are not included in the request will be deleted.
  • To keep specific data of fields in the table, the value of that field must be included in the request.
  • By specifying the ID of a table row (the ID can be retrieved by using the Get Record API), specific rows and fields can be updated. For more information, refer to the following article:
    Get Record
  • If a table row ID that does not exist is specified, the row will be added as a new row. In this case, rows that exist in the table but were not specified in the API, will be deleted.

Limitations

  • The maximum number of records that can be updated and/or added is 100.
  • If there are fields with the "Required field" option turned on and those fields hold no values (which could occur in cases where the App form was updated after some records were added to the App), those fields must be included in the request.
  • If the Update Records API fails, all updates will be canceled and no records will be updated.
  • The following fields cannot be updated:
    • The Field Mappings targets of the Lookup field
    • Status
    • Categories
    • Calculated
    • Assignee
    • Record number
    • Created by
    • Created datetime
    • Updated by
    • Updated datetime
  • If fields that do not exists inside the App are specified in the requests, these fields will be ignored.
  • If Calculated fields are specified values in the request, these values will be ignored.
  • If Text fields with the "Calculate automatically" option are specified values in the request, these values will be ignored.
  • Fields specified as the updateKey cannot be updated.
  • For other limitations, please check the Limitations section in the following article:
    Kintone REST API Overview