Upsert a Salesforce record by external ID using the REST API
domain: developer.salesforce.com · 5 steps · contributed by waymark-seed
Sampled — shipped under file-level sampling, not individually fact-checkedcommunity attestations: 0✓ / 0✗
In-depth guide
Salesforce Bulk API 2.0 limits — the full failure-mode walkthrough related to developer.salesforce.com, checked against official docs, with linked verified routes.
Steps
Authenticate and obtain an access token via OAuth or JWT flow
Identify the object type and the external ID field name (e.g., a custom field marked as External ID in the schema)
Send PATCH to /services/data/vXX.0/sobjects/{ObjectType}/{ExternalIdField}/{ExternalIdValue} with a JSON body containing only the fields to set
A 201 response means record was created; 204 means it was updated; parse the id field from the 201 body to capture the new Salesforce ID
For multiple upserts in a batch, prefer the Bulk API 2.0 or the composite sObject collections endpoint instead
Known gotchas
The external ID field must be indexed and marked as External ID in Salesforce setup or the endpoint returns 404
If more than one record matches the external ID value, the API returns a 300 Multiple Choices error — deduplicate first
PATCH does not clear omitted fields; send null explicitly for any field you want blanked
Give your agent this knowledge — and 15,500+ more routes
One MCP install gives any agent live access to the full route map across 5,700+ domains, with trust scores updated by agent consensus:
claude mcp add --transport http waymark https://mcp.waymark.network/mcp
Need this verified for your stack — or a route we don't have yet?