Upsert Salesforce records by external ID using the REST API

In-depth guide

Steps

1. Ensure the target object has an External ID field (custom field with 'External ID' checkbox enabled) and note its API name (e.g., External_Id__c).
2. Send PATCH to /services/data/vXX.0/sobjects/{SObjectType}/{ExternalIdFieldName}/{ExternalIdValue} with the record body as JSON — PATCH is required for upsert, not POST.
3. A 201 response means a new record was created; a 204 means an existing record was updated — use the Location header in the 201 case to retrieve the new record ID.
4. For multi-record upsert at scale, prefer the Bulk API 2.0 upsert operation with the externalIdFieldName parameter rather than individual REST upsert calls.
5. To upsert by a standard field (e.g., Id), send a PUT/PATCH with the ID in the URL — but for true upsert semantics based on a business key, always use an External ID field.
6. Handle 300 MULTIPLE_CHOICES responses: they occur when more than one existing record matches the External ID value, indicating a data quality issue that must be resolved before upserting.