Links

Overview

Process multiple records with a single request using batch functionality.
Batch requests allow you to process multiple records within a single API request. Batch processing is completed asynchronously, so when a batch is created, a batch ID will be returned in the response, and this batch ID can be queried periodically to determine the batch's status.

Limitations

  • Batch requests are limited to 100 records per batch. Each batch request will only count as 1 request for the purposes of API call limits, regardless of the number of records in the batch.
  • We allow a maximum of 10 batches in a queued or processing state per client. If you try to submit an additional batch during this time, you will receive a 429 response code. See API request limits for more information.
  • A batch request is limited to one of the following batch methods for the entire request.

Batch methods

Method name
Description
GET
Retrieve records.
POST
Create records.
PUT
Update records.
DELETE
Delete records.
EXECUTE-WORKFLOW
Execute workflow actions on records.
COPY
Copy records.

Batch options

Name
Value
Description
cancelIfRecordFails
true/false
If a record fails to meet criteria to process, do not process any of the records in the batch.

Batch statuses

Status
Description
Created
Batch created.
InProgress
Batch is processing.
Error
Batch resulted in an error.
Cancelled
Batch was cancelled. See cancelIfRecordFails batch option.
Complete
Batch completed successfully.

Batch records

Batch records are organized in a key-value collection, where the records are grouped by the char type ID. For example, the following JSON contains four records, two contacts (char type ID = 2) and two catalog items (char type ID = 1). This structure is the same for both creating and retrieving batch records.
{
"records": {
"2": [
{
"characteristics": {
"department": "Sales",
"first_name": "John",
"last_name": "Smith"
},
"template": {
"templateId": 1
},
"title": "Person 1"
},
{
"characteristics": {
"department": "Accounting",
"first_name": "Susan",
"last_name": "Williams"
},
"template": {
"templateId": 1
},
"title": "Person 2"
}
],
"1": [
{
"characteristics": {
"release_year": 2006
},
"template": {
"templateId": 1
},
"title": "Catalog 1"
},
{
"characteristics": {
"release_year": 2013
},
"template": {
"templateId": 1
},
"title": "Catalog 2"
}
]
}
}