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.
- 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.
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. |
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. |
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 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"
}
]
}
}