Update Record (PUT)

Update RecordPUT /record.json

Updates details of 1 record in an app by specifying its record number, or a different unique key.
URI
https://{subdomain}.kintone.com/k/v1/record.json
URI for Guest Space Apps
https://{subdomain}.kintone.com/k/guest/{SpaceID}/v1/record.json

Request Parameters

PARAMETER VALUE REQUIRED DESCRIPTION
app Integer or String Yes The app ID.
id Integer or String Conditionally Required The Record ID of the record to be updated. Required, if updateKey will not be specified.
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.
revision Integer or String Optional The expected revision number. If the value does not match, an error will occur and the record will not be updated. If the value is not specified or is -1, the revision number will not be checked.
record Object optional Field codes and values are specified in this object. If ignored, the record will not be updated. For field type specs, check the Field Types page.

*the API will result in an error if both id and updateKey are specified

Request body when specifying a record id

{
    "app": (APP ID),
    "id": (RECORD ID),
    "revision": (REVISION NUMBER), // leave blank if not needed
    "record": {
        "(FIELD CODE)": {
            "value": (FIELD VALUE)
        },
        // For the field in the first row of the table
        "(FIELD CODE OF TABLE)": {
            "value": {
                "0":{
                    "value": {
                        "(FIELD CODE)": {
                            "value": (FIELD VALUE)
                        }
                    }               
                }
            }
        }
    }
}

Request body when specifying a unique key

{
    "app": (APP ID),
    "updateKey": {
        "field": "(FIELD CODE OF UNIQUE KEY)",
        "value": "(FIELD VALUE)"
    },
    "revision": (REVISION NUMBER), // leave blank if not needed
    "record": {
        "(FIELD CODE)": {
            "value": (FIELD VALUE)
        },
        // For the field in the first row of the table
        "(FIELD CODE OF TABLE)": {
            "value": {
                "0":{
                    "value": {
                        "(FIELD CODE)": {
                            "value": (FIELD VALUE)
                        }
                    }               
                }
            }
        }
    }
}

Sample Request

Request Header

PUT /k/v1/record.json HTTP/1.1
Host: example.kintone.com:443
X-Cybozu-Authorization: a2ludG9uZTpkZXZlbG9wZXI=
Content-Type: application/json

Sample request body when specifying a record id

When updating a record of an app with an app number of 777:

FIELD TYPE FIELD CODE VALUE
Record number   1
Revision   4
Multi-line text string_multi this value has been updated
{
    "app": 777,
    "id": 1,
    "revision": 4,
    "record": {
        "string_multi": {
            "value": "this value has been updated"
        }
    }
}

Sample request body when specifying a unique key

When updating a record of an app with an app number of 777:

FIELD TYPE FIELD CODE VALUE
A field with the "Prohibit duplicate values" option turned on unique_key CODE123
Revision   4
Multi-line text string_multi this value has been updated
{
    "app": 777,
    "updateKey": {
        "field": "unique_key",
        "value": "CODE123"
    },
    "revision": 4,
    "record": {
        "string_multi": {
            "value": "this value has been updated"
        }
    }
}

Sample Response

The Revision number will be returned.

{
    "revision": "5"
}

JavaScript Samples

kintone REST API Request Example

var body = {
    "app": 100,
    "id": 200,
    "record": {
        "singleline_fieldcode": {
            "value": "ABC"
        }
    }
};
 
kintone.api(kintone.api.url('/k/v1/record', true), 'PUT', body, function(resp) {
        // success
        console.log(resp);
    }, function(error) {
        // error
        console.log(error);
    }
);

XMLHttpRequest Example

var url = 'https://{subdomain}.kintone.com/k/v1/record.json';
var body = {
    "app": 100,
    "id": 20,
    "record": {
        "singleline_fieldcode": {
            "value": "ABC"
        }
    },
    // CSRF TOKEN: Needs to be set when using API (POST, PUT, DELETE) from kintone
    "__REQUEST_TOKEN__": kintone.getRequestToken()
};
 
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));

Update RecordsPUT /records.json

Updates details of multiple records in an app, by specifying their record number, or a different unique key.
URI
https://{subdomain}.kintone.com/k/v1/records.json
URI for Guest Space Apps
https://{subdomain}.kintone.com/k/guest/{SpaceID}/v1/records.json

Request Parameters

PARAMETER VALUE REQUIRED DESCRIPTION
app Integer or String Yes The app ID.
records Array Yes Holds an array of objects that include id/updateKey, revision and record objects.
id Integer or String Conditionally Required The Record ID of the record to be updated. Required, if updateKey will not be specified.
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.
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.
record Object Optional Field codes and values are specified in this object. If ignored, the record will not be updated. For field type specs, check the Field Types page.

Request Body (for n records)

{
    "app": (APP ID),
    "records": [
        {   // First record data
            "id": (RECORD ID),
            "revision": (REVISION NUMBER),// leave blank if not needed
            "record": {
                "(FIELD CODE)": {
                    "value": (FIELD VALUE)
                },
                "(FIELD CODE)": {
                    "value": (FIELD VALUE)
                }
            }
        },
        {   // Second record data
            "id": (RECORD ID),
            "revision": (REVISION NUMBER), // leave blank if not needed
            "record": {
                "(FIELD CODE)": {
                    "value": (FIELD VALUE)
                },
                "(FIELD CODE)": {
                    "value": (FIELD VALUE)
                }
            }
        },
       {   // nth record data
            "id": (RECORD ID),
            "revision": (REVISION NUMBER), // leave blank if not needed
            "record": {
                "(FIELD CODE)": {
                    "value": (FIELD VALUE)
                },
                "(FIELD CODE)": {
                    "value": (FIELD VALUE)
                }
            }
        }
    ]
}

Sample Request

When updating 2 records of an app with an app number of 777:

First Record

FIELD TYPE FIELD CODE VALUE
Record number   1
A field with the "Prohibit duplicate values" option turned on unique_key CODE123
Revision   4
Single-line text string_1 Silver plates

Second Record

FIELD TYPE FIELD CODE VALUE
Record number   2
A field with the "Prohibit duplicate values" option turned on unique_key CODE456
Revision   1
Multi-line text string_multi The quick brown fox.

Sample request body when specifying a record id

{
    "app": 777,
    "records": [
        {
            "id": 1,
            "revision": 4,
            "record": {
                "string_1": {
                    "value": "Silver plates"
                }
            }
        },
        {
            "id": 2,
            "revision": 1,
            "record": {
                "string_multi": {
                    "value": "The quick brown fox."
                }
            }
        }
    ]
}

Sample request body when specifying a unique key

{
    "app": 777,
    "records": [
        {
            "updateKey": {
                "field": "unique_key",
                "value": "CODE123"
            },
            "revision": 4,
            "record": {
                "string_1": {
                    "value": "Silver plates"
                }
            }
        },
        {
            "updateKey": {
                "field": "unique_key",
                "value": "CODE456"
            },
            "revision": 1,
            "record": {
                "string_multi": {
                    "value": "The quick brown fox."
                }
            }
        }
    ]
}

Sample Response

The Record IDs and revisions for each updated record will be returned.

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

JavaScript Samples

kintone REST API Request Example

var body = {
    "app": kintone.app.getId(),
    "records": [
        {
            "id": 1,
            "record": {
                "singleline_fieldcode": {
                    "value": "ABC"
                }
            }
        },
        {
            "id": 2,
            "record": {
                "singleline_fieldcode": {
                    "value": "ABC"
                }
            }
        }
    ]
};

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

XMLHttpRequest Example

var url = 'https://{subdomain}.kintone.com/k/v1/records.json';
var body = {
    "app": 100,
    "records": [
        {
            "id": 1,
            "record": {
                "singleline_fieldcode": {
                    "value": "ABC"
                }
            }
        },
        {
            "id": 2,
            "record": {
                "singleline_fieldcode": {
                    "value": "ABC"
                }
            }
        }
    ],
    // CSRF TOKEN: Needs to be set when using API (POST, PUT, DELETE) from kintone
    "__REQUEST_TOKEN__": kintone.getRequestToken()
};
 
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));

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, you must include the value of that field in the request.
  • If you specify an id of a table row (which can be retrieved by using the Get Record API), you can update specific rows and fields.

Limitations

  • You must have permission to edit records in the app.
  • The maximum number of records that can be update is 100.
  • If there are fields with the "Required field" option turned on, 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
  • For other limitations, please check the Limitations on this page.
Was this article helpful?
0 out of 0 found this helpful
Comments
Please sign in to leave a comment.