---
schema_version: "1"
id: 9acf1f2cf40d160804b4c3704a8d0480d272a46bb1f31be8fb01cbede861f614
title: Upsert Records Using sObject Rows by External ID
collection: developer
version: current
locale: en-us
portal_url: https://docs.salesforce.com/developer/current/en-us/platform/api-rest/guides/resources/resources-sobject-upsert-patch.md
canonical_url: https://developer.salesforce.com/docs/platform/api-rest/guide/resources-sobject-upsert-patch.html
source_site: developer.salesforce.com
content_type: documentation
content_hash: 25091169b7848c86f4b91ce39299f6556639b3f92b1670c53e719246f7ba4e06
products:
  - REST API Developer Guide
  - Platform Developer Content
---

# 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 exists, the request either creates a 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. To prevent a new record from being created, use the `updateOnly` parameter.
-   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.

If you’re upserting a record for an object that has a custom field with both the `External ID` and `Unique` attributes selected (a unique index), you don’t need any special permissions. The `Unique` attribute prevents the creation of duplicates. If you’re 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.

**note:** For security reasons, some Top Level Domains (TLD) can conflict with certain file format extensions. Adjust your implementation to work around such cases.

For example, using an email address, such as `example@email.inc`, as the External ID returns a “404 not found” error.

There are several workarounds to handle conflicting TLDs.

-   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 request.
-   Use SOAP API instead of REST API for upsert requests.
-   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 request.

## Syntax

**URI:** `/services/data/vXX.X/sobjects/sObject/fieldName/fieldValue`

**Formats:** JSON, XML

**HTTP Method:** PATCH

**Authentication:** `Authorization: Bearer token`

**Parameters**

|Parameter|Description|
|---------|-----------|
|`updateOnly`|An optional parameter that prevents a new record from being created. Forces the upsert to behave like an update when `updateOnly=true` is used.|

## Example

For examples of creating and updating records based on external IDs, see [Insert or Update (Upsert) a Record Using an External ID](https://developer.salesforce.com/docs/platform/api-rest/do-me/dome-upsert.md).

**See Also**  


-   [Object Reference for the Salesforce Platform](https://developer.salesforce.com/docs/atlas.en-us.object_reference.meta/object_reference/)