Salesforce Facts: External IDs

4 min readMar 13, 2023

Definition

An External ID is a custom field set as “External Id” In the user interface. The field type must be a text, number, auto-number or email field.

A field set as an External ID can contain any value, but generally an external ID contains record IDs from a system outside of Salesforce so you can match against this field during import or integration, or when upserting records.

The Facts

An External ID is not unique

For an External ID to become unique you need to check the checkbox unique.

An External ID is indexed

When you create a custom field and mark it as an external ID, Salesforce will automatically create an index for you. This will allow the queries running on this field to be more selective and therefore faster.

Up to 25 External IDs

You can have up to 25 external IDs because there’s a limit of 25 indexes per object. This limits is a soft limit that can be increased by contacting Salesforce Support.
Once you reach the limit you see the error message Error: External ID and Unique field limit exceeded.
Note that this limits is shared for all custom indexed fields (external IDs, unique fields, custom indexes).

An External ID can be used for upserting records

Upsert uses the external ID to determine whether it should create a new record or update an existing one, for that we have 4 use cases:
— Use Case #1 — If the external ID is not matched, then a new record is created.
— Use Case #2 — If the external ID is matched once, then the existing record is updated.
— Use Case #3 — If the external ID is matched multiple times, then an error is reported.
— Use Case #4 — When batch updating multiple records where the external ID is the same for two or more records in your batch call, those records will be marked as errors.

Insert Vs Upsert

The field Text_ExternalID_Unique__c is marked as unique, therefore the code below will show the error System.DmlException: Insert failed. First exception on row 1; first error: DUPLICATE_VALUE, duplicate value found: Text_ExternalID_Unique__c duplicates value on record with id: 0018d00000TYfdc: []:

List<Account> accounts = new List<Account>();

For (Integer i = 0; i <= 3; i++){
    
    Account acc = new Account();
    acc.Name = 'Acc 1';
    acc.Text_ExternalID__c  = 'External ID #1';
    
    // All the records will have the same value
    // This will raise an error as this field is marked as unique
    acc.Text_ExternalID_Unique__c  = 'External Unique ID #1';

    accounts.add(acc);
}

insert accounts;

But if we change the code slightly to make the field values for Text_ExternalID_Unique__c unique as in the code below, the insert will work:

List<Account> accounts = new List<Account>();

For (Integer i = 0; i <= 3; i++){
    
    Account acc = new Account();
    acc.Name = 'Acc 1';
    acc.Text_ExternalID__c  = 'External ID #1';
    
    // Making the values for this field unique
    acc.Text_ExternalID_Unique__c  = 'External Unique ID #' + i;
    
    acc.active__c = 'true';
    accounts.add(acc);
}

insert accounts;

Now if try to upsert using the code below it won’t work, as in the same batch we are providing multiple times the same External ID and Salesforce does not know which one to use for updating, therefore we’ll get ther error System.DmlException: Upsert failed. First exception on row 0; first error: DUPLICATE_VALUE, Duplicate external id specified: External Unique ID #1: [Text_ExternalID__c]:
Not that this error will raise either we use the Unique External ID or the Not Unique External ID.

List<Account> accounts = new List<Account>();

For (Integer i = 0; i <= 3; i++){
    
    Account acc = new Account();
    acc.Name = 'Acc 1';
    
    // All the records will have the same value
    /* This will raise an error as Salesforce does not know
       which record to update */
    acc.Text_ExternalID__c  = 'External ID #1';

    /* The same error message would have been raised
       if we used this field for the upsert */
    acc.Text_ExternalID_Unique__c  = 'External Unique ID #1';

    accounts.add(acc);
}

upsert accounts Text_ExternalID__c;