SObject Rows by External ID

Creates new records or updates existing records (upserts records) 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, the REST API returns a 300 response with the list of matching records.

URI

/vXX.X/sobjects/SObjectName/fieldName/fieldValue

Formats

JSON, XML

HTTP Method

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

Authentication

Authorization: Bearer token

Parameters

None

Usage

As a special case, in API version 37.0 and later, you can use this resource to create a record by POSTing to /vXX.X/sobjects/SObjectName/Id. This pattern represents the use of Id as the specified external ID field and null as the value. It’s useful when you’re writing code to upsert multiple records by different external IDs and you don’t want to request a separate resource.

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.