External IDs and upsert for retaining legacy identifiers
Key Takeaway
To upsert on a legacy identifier, first create a custom External ID field (text, number, or email) on the target object and fill it with those identifiers.
When you migrate data into Salesforce, every record gets a new Salesforce record ID, so links that depended on the legacy system's IDs break. An External ID is a custom field that stores a record's identifier from the outside system. Upsert uses that value to decide whether to create or update a record and to link child records to their parents. So a migration can keep legacy identifiers, avoid duplicates, and rebuild relationships.
Why legacy links break
Salesforce links related records by unique record IDs, not by record names. Migrated records get new IDs in the target org, so every legacy ID that a related record points to must be replaced with the new ID, or the relationship is lost.
A clinic group's old billing system links a Contact to its account through the account ID BILL-2041. After the migration, that Account has a new Salesforce record ID. The Contact's row still says BILL-2041, so the link is lost unless that value is replaced with the new ID.
There are two common ways to replace legacy IDs. You can match old IDs to new IDs with Excel's VLOOKUP and update the import files. When that is not practical, you can create a custom External ID field and import related records using External ID relationships.