Upsert Records

Upserting New Records with an External ID

This example uses the PATCH method to insert a new record. It assumes that an external ID field, “customExtIdField__c,” has been added to Account. It also assumes that an Account record with a customExtIdField value of 11999 doesn’t already exist.

Note that in this example, we're able to create the job and upload the record data in a single call.

Example for upserting a record that doesn’t yet exist

1curl https://MyDomainName.my.salesforce.com/services/data/v57.0/sobjects/Account/customExtIdField__c/11999 -H 'Authorization: Bearer 00DE0X0A0M0PeLE!AQcAQH0dMHEXAMPLEzmpkb58urFRkgeBGsxL_QJWwYMfAbUeeG7c1EXAMPLEDUkWe6H34r1AAwOR8B8fLEz6nEXAMPLE' -H "Content-Type: application/json" -H "X-PrettyPrint:1" -d @newrecord.json -X POST

Example JSON request body newrecord.json file

1{
2    "Name" : "California Wheat Corporation",
3    "Type" : "New Customer"
4}

Example JSON response

The successful response is:

1{
2 "id":"0018a00001rBqb8AAC",
3 "success":true,
4 "errors":[],
5 "created":true
6 }

The HTTP status code is 201 (Created).

The created parameter is present in the response in API version 46.0 and later. It doesn't appear in earlier versions.

Note

Error responses

Incorrect external ID field:

1{
2    "message" : "The requested resource does not exist",
3    "errorCode" : "NOT_FOUND"
4}

Upserting Existing Records with an External ID

This example uses the PATCH method to update an existing record. It assumes that an external ID field, “customExtIdField__c,” has been added to Account and an Account record with a customExtIdField value of 11999 exists. The request uses updates.json to specify the updated field values.

Example of upserting an existing record

1curl https://MyDomainName.my.salesforce.com/services/data/v57.0/sobjects/Account/customExtIdField__c/11999 -H "Authorization: Bearer token" -H "Content-Type: application/json" -d @updates.json -X PATCH

Example JSON request body updates.json file

1{
2    "BillingCity" : "San Francisco"
3}

Example JSON response

In API version 46.0 and later, the HTTP status code is 200 (OK) and the successful response is:

1{
2    "id" : "001D000000Kv3g5IAB",
3    "success" : true,
4    "errors" : [ ],
5    "created": false
6}

In API version 45.0 and earlier, the HTTP status code is 204 (No Content) and there isn’t a response body.

Error responses

If the external ID value isn't unique, an HTTP status code 300 is returned, plus a list of the records that matched the query.

If the external ID field doesn't exist, an error message and code is returned:

1{
2    "message" : "The requested resource does not exist",
3    "errorCode" : "NOT_FOUND"
4}

Inserting New Records Using Id as the External ID

This example uses the POST method as a special case to insert a record where the Id field is treated as the external ID. Because the value of Id is null, it’s omitted from the request. This pattern is useful when you’re writing code to upsert multiple records by different external IDs and you don’t want to request a separate resource. POST using Id is available in API version 37.0 and later.

Example of inserting a record that doesn’t yet exist

1curl https://MyDomainName.my.salesforce.com/services/data/v57.0/sobjects/Account/Id -H "Authorization: Bearer token" -H "Content-Type: application/json" -d @newrecord.json -X POST

Example JSON request body newrecord.json file

1{
2    "Name" : "California Wheat Corporation",
3    "Industry" : "Agriculture"
4}

Example JSON response

The successful response is:

1{
2    "id" : "001D000000Kv3g5IAB",
3    "success" : true,
4    "errors" : [ ],
5    "created": true
6}

The HTTP status code is 201 (Created).

The created parameter is present in the response in API version 46.0 and later. It doesn't appear in earlier versions.

Note