Salesforce Sales Cloud: GET /PATCH by externalId Functionality

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.

Image_2019-11-11_at_3.15.43_PM.png

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.