How to upsert related Salesforce records with an External ID (load Accounts before Contacts)

AI-Assisted

By Richard C, AIL Studio

This walkthrough follows Salesforce Help. It was not run in a Salesforce org or in the Data Loader desktop app. Data Loader labels below are quoted from the Help article, not from a live Data Loader window.

Your Contact CSV still has the source system’s Account key. Salesforce will not accept that key as AccountId. Relationships are stored as record IDs, and those IDs are new in the target org.

Salesforce Help 000384648 (opened this turn; publish date Jul 3, 2026) puts it this way: “Record relationships in Salesforce are maintained through unique record IDs rather than record names.” Legacy IDs “must be replaced with the newly generated IDs from the target org.” A common approach is a VLOOKUP of those new IDs. The same article says that if VLOOKUP is not practical, a custom External ID field populated with the source identifier “allows related records to be imported using External ID relationships.”

This how-to is that second path: fill a unique External ID on Account, load Accounts first, then upsert Contacts by mapping the Account-key column to Account:Your_External_ID__c.

1. Create and fill a unique External ID on Account

Salesforce Help 000383207 (opened this turn; publish date Jul 5, 2026) says to create a custom field with the data type Text on the parent object and select the External ID and Unique attributes, or use an existing External ID field.

Use your own API name. The examples below use Legacy_Account_Id__c as a sample name. If you pick something else, the mapping syntax later becomes Account:That_Field__c.

If the Accounts already exist and the External ID is blank, the same article describes exporting those Accounts (include the Salesforce IDs), filling the External ID, and updating the existing records by mapping Id and the External ID field.

If the Accounts do not exist yet, map the source key into the External ID when you insert or upsert the Account file. The Help article recommends choosing values that already appear in the child file, so Contacts can match the same key.

2. Load Accounts before Contacts

000384648’s recommended import order for core objects starts with Accounts, then Campaigns, then Contacts, then Opportunities (then Cases, Price Books, Products, Leads and Contracts). This tutorial stays on Accounts, then Contacts. The rest of that list was not walked through here.

Always back up first. 000383207 says to back up before any Data Loader operation, then “Run a test with one or a small subset of records” and verify the records in Salesforce before you load the full file.

You can insert the Account file, which is how 000383207 loads new parent records, or upsert it matching on the External ID. The SOAP API upsert() call creates a record when the external ID isn’t matched and updates the existing record when it is matched one time; only Upsert lets a later rerun update the same Account instead of creating another row, and that needs the field to be unique. Matching by external ID is case-insensitive only if the field has the Unique attribute and the Treat “ABC” and “abc” as duplicate values (case insensitive) option selected.

3. Upsert Contacts and map the Account relationship

Prepare the Contact CSV with the source Account key in its own column. Do not put that key in AccountId. AccountId expects a Salesforce Account Id.

The Data Loader steps below are the wording from 000383207, written for a parent “Object A” and a child “Object B.” Here Object A is Account and Object B is Contact:

1. Click Upsert.
2. Select Contact.
3. Click Browse, select the Contact CSV, then click Next.
4. In Step 2, choose your related objects, select the Account External ID field from the Account drop-down.
5. In step 3, mapping, map the Contact file’s Account-key column to the Salesforce field named with the syntax [ObjectName]:[ExternalIDField__c]. For the sample field, that name is Account:Legacy_Account_Id__c.

The same article says this “eliminates the process of importing Object A records, exporting the new IDs, matching them up in Excel and then importing the child records.”

4. Example data

Example data (not a customer org, and not the result of a Salesforce load). Names, keys and addresses are invented. The email addresses use the reserved example.invalid domain. Do not import these rows into a live org.

Example Account CSV:

Example Contact CSV. Account_Legacy_Key is the source Account key, not a Salesforce Id:

Expected mapping for the relationship: Account_Legacy_Key → Account:Legacy_Account_Id__c. Upsert the two Accounts first, matching on Legacy_Account_Id__c. Then upsert the Contacts.

Renee should resolve to Example Aster Labs (AC-001). Sam should resolve to Example Blue Orchard (AC-002). Nora’s key AC-999 is not on either Account, so Data Loader cannot resolve that lookup. That failure belongs in the error file Data Loader writes. This recipe does not invent a parent for a missing key. The exact error text was not captured here, because the rows were not loaded into an org.

5. What still breaks

• Blank or duplicate External IDs. Unique is what stops two Accounts sharing the same key. Upsert is not a promise of zero duplicates if the field is not unique, or if you use Insert instead of Upsert.
• The parent row was not loaded yet, or you mapped the child file before the Account upsert finished.
• Lookup filters or validation rules can block a row. Treat those as possible causes to check in the error file, not as results tested here.
• 000383207 notes that not every reference field can be mapped to an External ID. Polymorphic fields such as Activity WhatId (Related To) and WhoId (Name), and a custom object’s Owner field, “do not allow mapping to external IDs.”

A successful upsert also does not prove the source key itself was right. If the Contact file already pointed at the wrong company, Data Loader will faithfully attach it there.

After the load, still review the parents: wrong-parent Contacts, orphan Contacts, a Contact export check for orphans, duplicate External IDs and picklist mismatches, and grouping Data Loader error rows.

An External ID upsert can relate Contacts to Accounts without a post-load VLOOKUP. It will not catch a Contact whose source key already pointed at the wrong company — that needs a before-and-after parent-key compare. If you want that check in one browser workbook, RecordBridge (US$49, one-time) compares Account and Contact CSV exports and flags those mismatches. It does not run the load or replace your firm’s go-live sign-off.