---
schema_version: "1"
id: 943816a4f32096903da54c81236812956ebe309ac08eb4713b4b99ea8cdcdcba
title: Upsert Records Using sObject Collections
collection: developer
version: current
locale: en-us
portal_url: https://docs.salesforce.com/developer/current/en-us/platform/api-rest/guides/resources/resources-composite-sobjects-collections-upsert.md
canonical_url: https://developer.salesforce.com/docs/platform/api-rest/guide/resources-composite-sobjects-collections-upsert.html
source_site: developer.salesforce.com
content_type: documentation
content_hash: 112220886e14d84166fd3ba788a33c5554dd779888cc0be5b1fcd69b69b6eb17
products:
  - REST API Developer Guide
  - Platform Developer Content
---

# Upsert Records Using sObject Collections

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.

-   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`.

    **note:** 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](https://developer.salesforce.com/docs/platform/api-rest/do-me/dome-sobject-insert-update-blob.md#using-sobject-collections-to-insert-a-collection-of-blob-records).

-   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.

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.

## Syntax

**URI:** `/services/data/vXX.X/composite/sobjects/SobjectName/ExternalIdFieldName`

**Formats:** JSON, XML

**HTTP Method:** PATCH

**Authentication:** `Authorization: Bearer token`

**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`.|
|`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.|

**Note:** 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](https://developer.salesforce.com/docs/platform/api-rest/guide/resources-composite-allornone.md).

## Example

**Example Request**

```nolang
curl -X PATCH https://MyDomainName.my.salesforce.com/services/data/v68.0/composite/sobjects/Account/MyExtId__c -H "Authorization: Bearer token" -H "Content-Type: application/json" -d "@exampleRequestBody.json"
```

**Example Request Body**

```nolang
{
    "allOrNone" : false,
    "records" : [{
        "attributes" : {"type" : "Account"},
        "Name" : "Company One",
        "MyExtId__c" : "AAA"
    }, {
        "attributes" : {"type" : "Account"},
        "Name" : "Company Two",
        "MyExtId__c" : "BBB"
    }]
}
```

**Example Response Body**

```nolang
HTTP/1.1 200 OK
[
    {
        "id": "001xx0000004GxDAAU",
        "success": true,
        "errors": [],
        "created": true
    },
    {
        "id": "001xx0000004GxEAAU",
        "success": true,
        "errors": [],
        "created": false
    }
]
```

**Example Response Body (Some Items Failed and `allOrNone` is `false`)**

```nolang
HTTP/1.1 200 OK

[
   {
      "id" : "001xx0000004GxDAAU",
      "success" : true,
      "errors" : [ ]
   },
   {
      "success" : false,
      "errors" : [
         {
            "statusCode" : "MALFORMED_ID",
            "message" : "Contact ID: id value of incorrect type: 001xx0000004GxEAAU",
            "fields" : [
               "Id"
            ]
         }
      ]
   }
]
```

**Example Response Body (Some Items Failed and `allOrNone` is `true`)**

```nolang
HTTP/1.1 200 OK

[
   {
      "id" : "001xx0000004GxDAAU",
      "success" : false,
      "errors" : [
         {
            "statusCode" : "ALL_OR_NONE_OPERATION_ROLLED_BACK",
            "message" : "Record rolled back because not all records were valid and the request was using AllOrNone header",
            "fields" : [ ]
         }
      ]
   },
   {
      "success" : false,
      "errors" : [
         {
            "statusCode" : "MALFORMED_ID",
            "message" : "Contact ID: id value of incorrect type: 001xx0000004GxEAAU",
            "fields" : [
               "Id"
            ]
         }
      ]
   }
]
```

**See Also**  


-   [sObject Rows by External ID](https://developer.salesforce.com/docs/platform/api-rest/guide/resources-sobject-upsert.md)