Batch Resource

Use this resource to minimize the number of round-trips between the client and the server. For example, in a mobile app, when a user taps the button to like a feed item, the response body includes information about the like, but it doesn’t include the total number of likes on the feed item. To like the feed item, POST a request to /chatter/feed-elements/feedElementId/capabilities/chatter-likes/items. To get the like total, GET the feed item information from /chatter/feed-elements/feedElementId/capabilities/chatter-likes/items.

Add both requests to a Generic Batch Collection Input request body and send them both in a single POST request to /connect/batch:

The requests in a batch are called subrequests. All subrequests are executed in the context of the same user. Subrequests are independent and information can’t be passed between them. Subrequests execute serially in their order in the request body. When a subrequest executes successfully, it commits its data. Commits are reflected in the output of later subrequests (as in the previous example which liked a feed item then got the total number of likes). If a subrequest fails, commits made by previous subrequests are not rolled back.

Resource

Available since version

28.0

Requires Chatter

No

HTTP methods

POST

Request body

Generic Batch Collection Input

Root XML Tag

<batch>

JSON

Properties

Name	Type	Description	Available Version
batchRequests	Generic Batch Input[]	Collection of Batch Request Input request bodies containing the subrequest URLs to execute.	28.0
haltOnError	Boolean	Controls whether Salesforce stops processing subrequests if a subrequest fails. The default value is false. If the value is false and a subrequest in the batch does not complete, Salesforce attempts to execute subsequent subrequests in the batch. If the value is true and a subrequest in the batch doesn’t complete due to an HTTP response in the 400 or 500 range, Salesforce halts execution. It doesn’t attempt to execute subsequent subrequests in the batch. It returns an HTTP 412 status code and a BATCH_PROCESSING_HALTED error message for each subsequent subrequest indicating that a previous request was unsuccessful. The top-level request to /connect/batch returns HTTP 200, and the hasErrors property in the response is set to true. Before subrequests are executed, Salesforce verifies that the entire request, including subrequests, is formed properly. If it isn't, Salesforce returns an HTTP 400 Bad Request and doesn't execute subrequests, regardless of the value of haltOnError. Examples of a bad request are a subrequest using the wrong method or having an error in its URL. Note	28.0

Request parameters

None.

Response

Batch Results

Example

This example is a POST request made to https://instance_name/services/data/v45.0/connect/batch that includes the following request body containing two subrequests:

The Batch Results response body includes a Batch Result Item response body for each subrequest:

Example: haltOnError is true

This example is the same as the previous example but it includes an error in the first subrequest and haltOnError is set to true. Note that the first subrequest contains a typo.

The Batch Results response body includes a Batch Result Item response body for each subrequest. The top-level request to /connect/batch returns an HTTP 200, but the first subrequest returns an HTTP 404 because the resource can’t be found. Because haltOnError is true, the next subrequest returns an HTTP 412. Also note that hasErrors is true.

Post multiple comments with binary files

This example is a generic batch request to https://instance_name/services/data/v45.0/connect/batch that contains two subrequests. Each subrequest comments on a feed item and uploads a binary file to the comment.

Include the request body of each subrequest in the richInput properties.

Also include information about the binary parts in the binaryPartName and binaryPartNameAlias properties.

Here is the cURL example.

Here is the multipart/form-data request body.