Newer Version Available

This content describes an older version of this product. View Latest

Insert or Update (Upsert) a Record Using an External ID

You can use the SObject Rows by External ID resource to create records or update existing records (upsert) based on the value of a specified external ID field.

If the specified value doesn't exist, a new record is created.
If a record does exist with that value, the field values specified in the request body are updated.
If the value is not unique, REST API returns a 300 response with the list of matching records.

The following sections show you how to work with the external ID resource to retrieve records by external ID and upsert records.

Upserting New Records

This example uses the PATCH method to insert a new record. It assumes that an external ID field, “customExtIdField__c,” has been added to Account. It also assumes that an Account record with a customExtIdField value of 11999 does not already exist.

Example for upserting a record that does not yet exist

1curl https://yourInstance.salesforce.com/services/data/v20.0/sobjects/Account/customExtIdField__c/11999 -H "Authorization: Bearer token" -H "Content-Type: application/json" -d @newrecord.json -X PATCH

Example JSON request body newrecord.json file

1{
2    "Name" : "California Wheat Corporation",
3    "Type" : "New Customer"
4}

Example JSON response

The successful response is:

1{
2    "id" : "00190000001pPvHAAU",
3    "errors" : [ ],
4    "success" : true,
5    "created": true
6}

The HTTP status code is 201 (Created).

The created parameter is present in the response in API version 46.0 and later. It doesn't appear in earlier versions.

Note

Error responses

Incorrect external ID field:

1{
2    "message" : "The requested resource does not exist",
3    "errorCode" : "NOT_FOUND"
4}

For more information, see Status Codes and Error Responses.

Inserting New Records Using Id as the External ID

This example uses the POST method as a special case to insert a record where the Id field is treated as the external ID. Because the value of Id is null, it’s omitted from the request. This pattern is useful when you’re writing code to upsert multiple records by different external IDs and you don’t want to request a separate resource. POST using Id is available in API version 37.0 and later.

Example of inserting a record that does not yet exist

1curl https://yourInstance.salesforce.com/services/data/v37.0/sobjects/Account/Id -H "Authorization: Bearer token" -H "Content-Type: application/json" -d @newrecord.json -X POST

Example JSON request body newrecord.json file

1{
2    "Name" : "California Wheat Corporation",
3    "Type" : "New Customer"
4}

Example JSON response

The successful response is:

1{
2    "id" : "001D000000Kv3g5IAB",
3    "success" : true,
4    "errors" : [ ],
5    "created": true
6}

The HTTP status code is 201 (Created).

The created parameter is present in the response in API version 46.0 and later. It doesn't appear in earlier versions.

Note

Upserting Existing Records

This example uses the PATCH method to update an existing record. It assumes that an external ID field, “customExtIdField__c,” has been added to Account and an Account record with a customExtIdField value of 11999 exists. The request uses updates.json to specify the updated field values.

Example of upserting an existing record

1curl https://yourInstance.salesforce.com/services/data/v20.0/sobjects/Account/customExtIdField__c/11999 -H "Authorization: Bearer token" -H "Content-Type: application/json" -d @updates.json -X PATCH

Example JSON request body updates.json file

1{
2    "BillingCity" : "San Francisco"
3}

Example JSON response

In API version 46.0 and later, the HTTP status code is 200 (OK) and the successful response is:

1{
2    "id" : "001D000000Kv3g5IAB",
3    "success" : true,
4    "errors" : [ ],
5    "created": false
6}

In API version 45.0 and earlier, the HTTP status code is 204 (No Content) and there is no response body.

Error responses

If the external ID value isn't unique, an HTTP status code 300 is returned, plus a list of the records that matched the query. For more information about errors, see Status Codes and Error Responses.

If the external ID field doesn't exist, an error message and code is returned:

1{
2    "message" : "The requested resource does not exist",
3    "errorCode" : "NOT_FOUND"
4}

Upserting Records and Associating with an External ID

If you have an object that references another object using a relationship, you can use REST API to both insert or update a record and also reference another object using an external ID.

The following example creates a record and associates it with a parent record via external ID. It assumes the following:

A Merchandise__c custom object that has an external ID field named MerchandiseExtID__c.
A Line_Item__c custom object that has an external ID field named LineItemExtID__c, and a relationship to Merchandise__c.
A Merchandise__c record exists that has a MerchandiseExtID__c value of 123.
A Line_Item__c record with a LineItemExtID__c value of 456 does not exist. This is the record that gets created and associated to the Merchandise__c record.

Example of upserting a record and referencing a related object

1curl https://yourInstance.salesforce.com/services/data/v25.0/sobjects/Line_Item__c/LineItemExtID__c/456 -H "Authorization: Bearer token" -H "Content-Type: application/json" -d @new.json -X PATCH

Example JSON request body new.json file

Notice that the related Merchandise__c record is referenced using the Merchandise__c’s external ID field.

1{
2   "Name" : "LineItemCreatedViaExtID",
3   "Merchandise__r" :
4   {
5       "MerchandiseExtID__c" : 123
6   }
7}

Example JSON response

The successful response is:

1{
2    "id" : "a02D0000006YUHrIAO",
3    "errors" : [ ],
4    "success" : true,
5    "created": true
6}

The HTTP status code is 201 (Created).

The created parameter is present in the response in API version 46.0 and later. It doesn't appear in earlier versions.

Note

Error responses

If the external ID value isn't unique, an HTTP status code 300 is returned, plus a list of the records that matched the query. For more information about errors, see Status Codes and Error Responses.

If the external ID field doesn't exist, an error message and code is returned:

1{
2    "message" : "The requested resource does not exist",
3    "errorCode" : "NOT_FOUND"
4}

You can also use this approach to update existing records. For example, if you created the Line_Item__c shown in the example above, you can try to update the related Merchandise__c using another request.

Example for updating a record

1curl https://yourInstance.salesforce.com/services/data/v25.0/sobjects/Line_Item__c/LineItemExtID__c/456 -H "Authorization: Bearer token" -H "Content-Type: application/json" -d @updates.json -X PATCH

Example JSON request body updates.json file

This assumes another Merchandise__c record exists with a MerchandiseExtID__c value of 333.

1{
2   "Merchandise__r" :
3   {
4       "MerchandiseExtID__c" : 333
5   }
6}

Example JSON response

In API version 46.0 and later, the HTTP status code is 200 (OK) and the successful response is:

1{
2    "id" : "001D000000Kv3g5IAB",
3    "success" : true,
4    "errors" : [ ],
5    "created": false
6}

In API version 45.0 and earlier, the HTTP status code is 204 (No Content) and there is no response body.

If the relationship type is master-detail and the relationship is set to not allow reparenting, and you try to update the parent external ID, you get an HTTP status code 400 error with an error code of INVALID_FIELD_FOR_INSERT_UPDATE.

REST API Developer Guide

Insert or Update (Upsert) a Record Using an External ID

Upserting New Records

Inserting New Records Using Id as the External ID

Upserting Existing Records

Upserting Records and Associating with an External ID