How Salesforce External IDs Work?

Often times when migrating data from a system to salesforce or when trying to update records in Salesforce via an API callout from an external system, we wonder how to fetch existing records without using the Salesforce Id for each record.

Salesforce let’s us define external Ids which act as foreign keys to enable us to update, upsert or fetch data using unique keys that another system recognizes readily.

What are External Ids?

A field in Salesforce can be marked as an External Id to allow other system to reference it to update data.

External IDs are searchable in Salesforce and you can also use the Upsert API call with the External ID to refer to records when making changes via Data Loader.

Example use case for External IDs:
If you have an Oracle Account Id system that links with Salesforce, it may be more efficient for you to refer to the Oracle ID of account records from within Salesforce than using the Salesforce Account Id.

In this case, you can create a custom field and mark it as an ‘External ID’ in Salesforce and use it to capture and display the Oracle ID for each account.

Salesforce External Id

Note: You can have multiple records with the same External ID, though this it is not recommended.

How is an External Id different to a Unique Id field?

The ‘Unique ID’ field setting ensures that the same value can not be used in multiple records for that specific field.

External IDs are often created with the ‘Unique ID’ setting so that the External IDs will be unique to each record.

In order to use a custom field as an External Id in the Data Import Wizard, the field must also be marked as Unique.

Example:
You could create a 5 character text field and set that field as a ‘Unique ID’. If you enter ‘12345’ as the value in this field, you would not be able to use ‘12345’ as the value for that field in any other record. If you attempted to use ‘12345’ again for another record, a message would appear stating that the value is already in use.

Considerations for using External Ids

The following considerations must be kept in mind when setting an External Id field:

External ID fields must be Custom text fields, number or email fields.
External ID fields contain record IDs from systems outside Salesforce.
An object can have at most 7 External IDs’ fields.
Custom fields marked as unique also count against an object’s limit of 7 External IDs’ fields.
When using External Id to UPSERT a record, if the external ID isn’t matched, then a new record is created.
When using External Id to UPSERT a record, if the external ID is matched one time, then the record is updated. However, If the external ID is matched multiple times, then a 300 error is reported, and the record isn’t created or updated.
External Ids are considered case-insensitive but if the custom field has a separate “Unique” attribute then the case sensitive option for that field is selected which means Uppercase and Lowercase letters will not be considered identical.

Using External IDs in APEX

Salesforce allows External Ids to be easily used to link records together or upserting records using APEX code.

For example:

Before the new opportunity is inserted, the account record is added to this opportunity as an sObject through the Opportunity.Account relationship field.

Opportunity newOpportunity = new Opportunity( Name='OpportunityWithAccountInsert', StageName='Prospecting',
CloseDate=Date.today().addDays(7));

// Create the parent record reference.
// An account with external ID = 'SAP111111' already exists.
// This sObject is used only for foreign key reference
// and doesn't contain any other fields.
Account accountReference = new Account(MyExtID__c='SAP111111');

// Add the account sObject to the opportunity.
newOpportunity.Account = accountReference;

// Create the opportunity.
Database.SaveResult results = Database.insert(newOpportunity);

Using REST or SOAP API, records can be upserted in a single API call made to the Object by passing the External Id in the POST command.

For Example:

{
"method" : "POST",
"referenceId" : "NewCase",
"url" : "/services/data/v49.0/sobjects/Case/Ext12345",

"body" : {
"Subject": "New Case",
"Status":"New",
}
}

Conclusion

External IDs are very useful when data migrating from external systems or making native Salesforce API calls to upsert data where the Salesforce ID cannot be used.