sObject Rows by External ID

Creates new records or updates existing records (upserts records) based on the value of a specified external ID field. Use the PATCH method to upsert a record with an external ID. Upsert uses the value of the external ID to determine whether to create a new record or update the existing one.

If the external ID is not matched, then a new record is created according to the request body.
If the external ID is matched once, 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 is not created or updated.

Do not specify Id or an external ID field in the request body or an error is generated.

Note

For security reasons, some Top Level Domains (TLD) may conflict with certain file format extensions. Adjust your implementation to work around such cases. For example, when an email address is used as the External ID in the request URL, and the TLD ".inc" is used as part of the field value, the request returns a “404 not found” error.

For example,

returns a “404 not found” error.

Workarounds:

Use a different External ID field.
Create a new External ID field that is the same as the email field and replace the "." with an "_" to handle this case.
Run a query for emails ending in ".inc" to retrieve the record ID and use that for the upsert.
Use SOAP API instead of REST API for upsert operations.
Accept the email as a query parameter instead of a path parameter by creating a custom Apex REST API. Use Apex to perform the upsert operation.

Note

URI

/services/data/vXX.X/sobjects/sObject/fieldName/fieldValue

Formats

JSON, XML

HTTP Method

HEAD, GET, PATCH, DELETE, POST (see Usage section)

Authentication

Authorization: Bearer token

Parameters

None

Usage

If you are upserting a record for an object that has a custom field with both the External ID and Unique attributes selected (a unique index), you do not need any special permissions. The Unique attribute prevents the creation of duplicates. If you are upserting a record for an object that has the External ID attribute selected but not the Unique attribute selected, (a non-unique index) your client application must have the permission “View All Data” to execute this call.

As a special case, in API version 37.0 and later, you can create a record with a POST request to /vXX.X/sobjects/sObjectName/Id. Because Id has a null value, it is omitted from the request, and the record is created according to the request body. Upserting records with this method is useful because you can use the same resource in each POST request for each new record. In this case, you are not required to specify an external ID to create a record.

Examples

For an example of retrieving a record based on an external ID, see Retrieve a Record Using an External ID.
For examples of creating and updating records based on external IDs, see Insert or Update (Upsert) a Record Using an External ID.

REST API Developer Guide

sObject Rows by External ID