Upsert Records Using sObject Rows by External ID

Upserts a record based on the value of the specified external ID field. Based on whether the value of the external ID already exists, the request either creates a new record or updates an existing one.

If the external ID doesn't match an existing record, then a new record is created according to the request body.
If the external ID matches one existing record, then the existing record is updated according to the request body.
If the external ID matches multiple existing records, then a 300 error is returned, and no records are 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.

1curl https://MyDomainName.my.salesforce.com/services/data/v55.0/sobjects/Lead/Email/example@email.inc -H "Authorization: Bearer token" -X PATCH

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/sObjectName/fieldName/fieldValue

Formats

JSON, XML

HTTP Method

PATCH

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.

Examples

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

Upsert Records Using sObject Rows by External ID

See Also