Upsert Multiple Records with Fewer Round-Trips

Use a PATCH request with sObject Collections to either create or update (upsert) up to 200 records based on an external ID field. This method returns a list of UpsertResult objects. You can choose whether to roll back the entire request when an error occurs. This request is available in API version 46 and later.

Request Syntax

PATCH /services/data/vXX.X/composite/sobjects/SobjectName/ExternalIdFieldName

Parameters

Parameter	Description
allOrNone	Optional. Indicates whether to roll back the entire request when the creation of any object fails (`true`) or to continue with the independent creation of other objects in the request. The default is `false`. If the sObject Collections request is embedded in a Composite request, the Composite request’s `allOrNone` parameter can also affect the results. See allOrNone Parameters in Composite and Collections Requests. Note
records	Required. A list of sObjects. In a PATCH request using sObject Collections, set the `type` attribute for each object. Don’t set the `id` field for any object. Instead, use the external ID field specified in the request URI.

Parameter

Description

allOrNone

Optional. Indicates whether to roll back the entire request when the creation of any object fails (true) or to continue with the independent creation of other objects in the request. The default is false.

If the sObject Collections request is embedded in a Composite request, the Composite request’s allOrNone parameter can also affect the results. See allOrNone Parameters in Composite and Collections Requests.

Note

records

Required. A list of sObjects. In a PATCH request using sObject Collections, set the type attribute for each object. Don’t set the id field for any object. Instead, use the external ID field specified in the request URI.

Usage Guidelines

The list can contain up to 200 objects.
The list can contain objects only of the type indicated in the request URI.
Each object in the request body must contain an attributes map. The map must contain a value for type.
Using sObject Collections to insert blob data requires more values in the attributes map. For more information, see Using sObject Collections to Insert a Collection of Blob Records.
Note
Objects are created or updated in the order they’re listed in the request body. The UpsertResult objects are returned in the same order.
Only external ids are supported. Don’t use record ids.

Checking for Errors

If the request isn’t well formed, the API returns a 400 Bad Request HTTP Status. Fix the syntax of the request and try again.
If the request is well formed, the API returns a 200 OK HTTP Status. If an item was processed successfully, the success flag shows for that item. Error information is returned in the errors array.

Request Body Example

1PATCH /composite/sobjects/Account/MyExtId__c
2{
3    "allOrNone" : false,
4    "records" : [{
5        "attributes" : {"type" : "Account"},
6        "Name" : "Company One",
7        "MyExtId__c" : "AAA"
8    }, {
9        "attributes" : {"type" : "Account"},
10        "Name" : "Company Two",
11        "MyExtId__c" : "BBB"
12    }]
13}

Response Body Examples

This example shows a response when all the items were processed successfully.

1Status: 200
2[
3    {
4        "id": "001xx0000004GxDAAU",
5        "success": true,
6        "errors": [],
7        "created": true
8    },
9    {
10        "id": "001xx0000004GxEAAU",
11        "success": true,
12        "errors": [],
13        "created": false
14    }
15]

This example shows a response when some items caused errors and allOrNone is false.

1HTTP/1.1 200 OK
2
3[
4   {
5      "id" : "001xx0000004GxDAAU",
6      "success" : true,
7      "errors" : [ ]
8   },
9   {
10      "success" : false,
11      "errors" : [
12         {
13            "statusCode" : "MALFORMED_ID",
14            "message" : "Contact ID: id value of incorrect type: 001xx0000004GxEAAU",
15            "fields" : [
16               "Id"
17            ]
18         }
19      ]
20   }
21]

This example shows a response when some items caused errors and allOrNone is true.

1HTTP/1.1 200 OK
2
3[
4   {
5      "id" : "001xx0000004GxDAAU",
6      "success" : false,
7      "errors" : [
8         {
9            "statusCode" : "ALL_OR_NONE_OPERATION_ROLLED_BACK",
10            "message" : "Record rolled back because not all records were valid and the request was using AllOrNone header",
11            "fields" : [ ]
12         }
13      ]
14   },
15   {
16      "success" : false,
17      "errors" : [
18         {
19            "statusCode" : "MALFORMED_ID",
20            "message" : "Contact ID: id value of incorrect type: 001xx0000004GxEAAU",
21            "fields" : [
22               "Id"
23            ]
24         }
25      ]
26   }
27]

REST API Developer Guide