REST API Developer Guide

Clouds with binary code floating aboveCloud with binary code floating above

No Results

Search Tips:

  • Please consider misspellings
  • Try different search keywords
Introduction to REST API
Quick Start
Examples
Getting Information About My Organization
Working with Object Metadata
Working with Records
Create a Record
Update a Record
Delete a Record
Get Field Values from a Standard Object Record
Get Field Values from an External Object Record by Using the Salesforce ID
Get Field Values from an External Object Record by Using the External ID Standard Field
Get a Record Using an External ID
Insert or Update (Upsert) a Record Using an External ID
Traverse Relationships with Friendly URLs
Get a List of Deleted Records Within a Given Timeframe
Get a List of Updated Records Within a Given Timeframe
Delete Lightning Experience Event Series
Working with Searches and Queries
Get an Image from a Rich Text Area Field
Insert or Update Blob Data
Get Blob Data
Working with Recently Viewed Information
Managing User Passwords
Working with Approval Processes and Process Rules
Using Event Monitoring
Using Composite Resources
Generating an OpenAPI 3.0 Document for sObjects REST API (Beta)
Reference
PDF

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.

Where possible, we changed noninclusive terms to align with our company value of Equality. We maintained certain terms to avoid any effect on customer implementations.

Important

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

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:
{
    "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).

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

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

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:
{
    "message" : "The requested resource does not exist",
    "errorCode" : "NOT_FOUND"
}
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
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.

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.