We have recently enhanced the swagger of the Salesforce Sales Cloud element with the generic GET /{objectName}/fields/{name}/{externalID} and PATCH /{objectName}/fields/{name}/{externalID} endpoints. These can be used to retrieve or update, respectively, the desired records based on an externalId.
An external ID is a custom field that has the “External ID” attribute, meaning that it contains unique record identifiers from a system outside of Salesforce. Only the fields with the following data types can be external Ids: Number, Text, Email.
Using the GET /{objectName}/fields/{name}/{externalID}, as mentioned above, the customers can retrieve records with a specific external ID.
Example usage for retrieving a TEST_ID__c record using an external ID(accounts is the object name, the externalID field name is TEST_ID__c and the externalID field value is 589632):
curl -X GET
"https://api.cloud-elements.com/elements/api-v2/accounts/fields/TEST_ID__c/589632"
-H "accept: application/json"
-H "Authorization: User XXXXXX, Organization XXXXXX, ElementXXXXXX"The response payload has the following structure:
{
"LastModifiedDate": "2019-11-11T13:11:05.000+0000",
"IsDeleted": false,
"LastViewedDate": "2019-11-11T13:11:05.000+0000",
"LastReferencedDate": "2019-11-11T13:11:05.000+0000",
"Name": "TestName",
"SystemModstamp": "2019-11-11T13:11:05.000+0000",
"Type": "Prospect",
"CleanStatus": "Pending",
"CreatedById": "XXXXXXXXXXXX",
"OwnerId": "XXXXXXXXXXXX",
"CreatedDate": "2019-11-11T13:11:05.000+0000",
"RecordTypeId": "0121r000000eDEfAAM",
"attributes": {
"type": "Account",
"url": "/services/data/v46.0/sobjects/Account/XXXXXXXXXXXX"
},
"PhotoUrl": "/services/images/photo/XXXXXXXXXXXX",
"Id": "XXXXXXXXXXXX",
"TEST_ID__c": "589632",
"LastModifiedById": "XXXXXXXXXXXX"
}The PATCH /{objectName}/fields/{name}/{externalID} endpoint can be used to create records or update existing records (upsert) 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.
An example of a successful PATCH by externalId request(accounts is the object name, the externalID field name is TEST_ID__c and the externalID field value is 589632):
curl -X PATCH "https://api.cloud-elements.com/elements/api-v2/accounts/fields/TEST_ID__c/589632" -H "accept: application/json" -H "Authorization: User XXXXXX, Organization XXXXXX, Element XXXXXX" -H "Content-Type: application/json" -d "{ \"Name\": \"TestName\"}"
The response payload has the following structure:
{
"id": "XXXXXXX",
"success": true,
"created": true*
}* In case the record existed but has been updated, the created parameter value is set to false.
