Force.com REST API Developer's Guide

Clouds with binary code floating aboveCloud with binary code floating above

No Results

Search Tips:

  • Please consider misspellings
  • Try different search keywords
PDF

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 new 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://na1.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
3    "Name" : "California Wheat Corporation",
4    "Type" : "New Customer"
5
6}
Response
Successful response:
1{
2    "id" : "00190000001pPvHAAU",
3    "errors" : [ ],
4    "success" : true
5}

The response body is empty. HTTP status code 201 is returned if a new record is created.

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.

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 for upserting a record that already exists
1curl https://na1.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
3    "BillingCity" : "San Francisco"
4
5}
JSON example response
HTTP status code 204 is returned if an existing record is updated.
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 new record, and also reference another object using an external ID.

The following example creates a new 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 will get created and associated to the Merchandise__c record.
Example for upserting a new record and referencing a related object
1curl https://na1.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}
JSON example response
HTTP status code 201 is returned on successful create.
1{
2    "id" : "a02D0000006YUHrIAO",
3    "errors" : [ ],
4    "success" : true 
5}
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://na1.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}
JSON example response
HTTP status code 204 is returned if an existing record is updated.
Note that if your relationship type is master-detail and the relationship is set to not allow reparenting, and you try to update the parent external ID, you will get an HTTP status code 400 error with an error code of INVALID_FIELD_FOR_INSERT_UPDATE.