The Batch API lets you create or update a list of entities of the same type in a single API request. The request is processed asynchronously — the server may process records in any order.
Endpoint Send a PATCH request to /api/{entity}, where {entity} is the entity type:
PATCH /api/accounts HTTP / 1.1 Content-Type : application/vnd.api+json Accept : application/vnd.api+json
Creating records { "data" : [ { "type" : "entityType" , "attributes" : { ... }, "relationships" : { ... } }, { "type" : "entityType" , "attributes" : { ... }, "relationships" : { ... } } ] }
Updating records Mark records to be updated with the update meta property:
{ "data" : [ { "meta" : { "update" : true }, "type" : "entityType" , "id" : 1 , "attributes" : { ... }, "relationships" : { ... } }, { "meta" : { "update" : true }, "type" : "entityType" , "id" : 2 , "attributes" : { ... }, "relationships" : { ... } } ] }
Upsert records Mark records with the upsert meta property to create them if they don’t exist, or update them if they do:
{ "data" : [ { "meta" : { "upsert" : true }, "type" : "entityType" , "id" : 1 , "attributes" : { ... }, "relationships" : { ... } } ] }
See Upsert Operation for details.
Included items Related entities can be created or updated when processing primary entities. Place them in an included section at the root level alongside the data section.
{ "data" : [ { "type" : "entityType" , "attributes" : { ... }, "relationships" : { "relation" : { "data" : { "type" : "entityType1" , "id" : "included_entity_1" } } } } ], "included" : [ { "type" : "entityType1" , "id" : "included_entity_1" , "attributes" : { ... }, "relationships" : { ... } } ] }
To update included records, use the update meta property:
{ "included" : [ { "meta" : { "update" : true }, "type" : "entityType1" , "id" : "12" , "attributes" : { ... } } ] }
Example Request PATCH /api/accounts HTTP / 1.1 Content-Type : application/vnd.api+json Accept : application/vnd.api+json
Request body { "data" : [ { "type" : "accounts" , "attributes" : { "name" : "Gartner management group" } }, { "type" : "accounts" , "attributes" : { "name" : "Cloth World" } } ] }
Response The response contains the corresponding asynchronous operation created for the request:
{ "data" : { "type" : "asyncoperations" , "id" : "1" , "links" : { "self" : "http://your_domain.com/admin/api/asyncoperations/1" }, "attributes" : { "status" : "new" , "progress" : null , "createdAt" : "2020-03-11T17:41:17Z" , "updatedAt" : "2020-03-11T17:41:17Z" , "elapsedTime" : 0 , "entityType" : "accounts" , "summary" : null }, "relationships" : { "owner" : { "data" : { "type" : "users" , "id" : "1" } }, "organization" : { "data" : { "type" : "organizations" , "id" : "1" } } } } }
Async operation response fields Status of the asynchronous operation. Possible values: new, running, failed, success, cancelled.
The progress, in percentage, for the asynchronous operation.
Number of seconds the operation has been running.
The type of entity for which the operation was created.
When the operation was created.
When the operation was last updated.
The user who created the operation.
The organization the operation belongs to.
Summary statistics. Only populated when the operation completes successfully. Total accumulated time in milliseconds.
Number of items successfully read.
Number of items successfully written.
Number of errors that occurred.
Number of items successfully created.
Number of items successfully updated.
Checking operation status To check the status of an operation:
GET /api/asyncoperations/1 HTTP / 1.1 Accept : application/vnd.api+json
Successful completion: { "data" : { "type" : "asyncoperations" , "id" : "1" , "attributes" : { "status" : "success" , "progress" : 1 , "elapsedTime" : 3 , "entityType" : "accounts" , "summary" : { "aggregateTime" : 2737 , "readCount" : 2 , "writeCount" : 2 , "errorCount" : 0 , "createCount" : 2 , "updateCount" : 0 } } } }
Retrieving errors If some entities failed to process, use the asyncoperations/{id}/errors subresource:
GET /api/asyncoperations/1/errors HTTP / 1.1 Accept : application/vnd.api+json
{ "data" : [ { "type" : "asyncoperationerrors" , "id" : "3-1-1" , "attributes" : { "status" : 400 , "title" : "not blank constraint" , "detail" : "This value should not be blank." , "source" : { "pointer" : "/data/0/attributes/name" } } } ] }
Error object fields The HTTP status code applicable to the problem.
A short, human-readable summary of the problem type.
A human-readable explanation of this specific occurrence of the problem.
References to the source of the error. A JSON Pointer to the value in the request document that caused the error, e.g., /data/0 or /data/0/attributes/title. A path to the value in the request document that caused the error. Returned when pointer cannot be computed.