Insert or Update (Upsert) a Record Using an External ID
- If the external ID isn’t matched, then a new record is created according to the request body. To prevent a new record from being created, use the updateOnly parameter.
- If the external ID is matched one time, then the record is updated according to the request body.
- If the external ID is matched multiple times, then a 300 error is reported, and the record isn’t created or updated.
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 doesn’t exist.
- Example for upserting a record that doesn’t yet exist
-
curl https://MyDomainName.my.salesforce.com/services/data/v64.0/sobjects/Account/customExtIdField__c/11999 -H "Authorization: Bearer token" -H "Content-Type: application/json" -d @newrecord.json -X PATCH
If you want to update a record but not create it if it doesn't exist, add the updateOnly parameter to the URL. For example: https://MyDomainName.my.salesforce.com/services/data/v64.0/sobjects/Account/customExtIdField__c/11999?updateOnly=true
- Example JSON request body newrecord.json file
-
{ "Name" : "California Wheat Corporation", "Type" : "New Customer" }
- Example JSON response
- The successful response is:
{ "id" : "00190000001pPvHAAU", "errors" : [ ], "success" : true, "created": true }
The HTTP status code is 201 (Created).
- Error responses
- Incorrect external ID field:
{ "message" : "The requested resource does not exist", "errorCode" : "NOT_FOUND" }
- 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 doesn’t yet exist
-
curl https://MyDomainName.my.salesforce.com/services/data/v64.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
-
{ "Name" : "California Wheat Corporation", "Type" : "New Customer" }
- Example JSON response
- The successful response is:
{ "id" : "001D000000Kv3g5IAB", "success" : true, "errors" : [ ], "created": true }
The HTTP status code is 201 (Created).
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
-
curl https://MyDomainName.my.salesforce.com/services/data/v64.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
-
{ "BillingCity" : "San Francisco" }
- Example JSON response
- In API version 46.0 and later, the HTTP status code is 200 (OK) and the
successful response is:
{ "id" : "001D000000Kv3g5IAB", "success" : true, "errors" : [ ], "created": false }
In API version 45.0 and earlier, the HTTP status code is 204 (No Content) and there isn’t a 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:
{ "message" : "The requested resource does not exist", "errorCode" : "NOT_FOUND" }
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 reference another object using an external ID.
- 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 record gets created and related to the Merchandise__c record.
- Example of upserting a record and referencing a related object
-
curl https://MyDomainName.my.salesforce.com/services/data/v64.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.
{ "Name" : "LineItemCreatedViaExtID", "Merchandise__r" : { "MerchandiseExtID__c" : 123 } }
- Example JSON response
- The successful response is:
{ "id" : "a02D0000006YUHrIAO", "errors" : [ ], "success" : true, "created": true }
-
The HTTP status code is 201 (Created).
- 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:
{ "message" : "The requested resource does not exist", "errorCode" : "NOT_FOUND" }
- Example for updating a record
-
curl https://MyDomainName.my.salesforce.com/services/data/v64.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.
{ "Merchandise__r" : { "MerchandiseExtID__c" : 333 } }
- Example JSON response
- In API version 46.0 and later, the HTTP status code is 200 (OK) and the
successful response is:
{ "id" : "001D000000Kv3g5IAB", "success" : true, "errors" : [ ], "created": false }
In API version 45.0 and earlier, the HTTP status code is 204 (No Content) and there isn’t a response body.