Upsert Salesforce Accounts Safely with External IDs

Use a stable source-system key to test repeatable Account imports, distinguish External ID from Unique, and reconcile successes before retrying failures.

A weekly customer file arrives from another system. Some customers already exist in Salesforce; others are new. Inserting the whole file again can create duplicates, while updating by company name is an unreliable way to identify the intended record. An external-ID upsert gives the load a deliberate matching key.

Upsert combines two outcomes: update a matching record, or create one when no match exists. That second outcome is useful—and risky. A mistyped key can turn an intended update into a new Account. Start with a sandbox, a backup, and a small file whose expected results are written down.

Choose the identity before choosing the tool

This fictional example receives customer data from a billing system. Each customer has a stable identifier such as BILL-1042. Salesforce stores it in an Account text field called Billing Customer Key, with the API name Billing_Customer_Key__c.

Confirm with the source-system owner that this key is never reused for a different customer and remains stable when the company changes its name. Decide how whitespace, letter case, and leading zeroes are handled. Do not let spreadsheet formatting convert a meaningful identifier such as 001042 into 1042.

External ID and Unique do different jobs

In Setup, an External ID marks a field that can identify records using an external system’s value. The Unique setting prevents the same field value from being stored on multiple records. Selecting External ID alone does not guarantee unique values.

For this example, use a text field with both settings selected, subject to your agreed business key and text case-sensitivity policy. If you are changing an existing field, inspect and resolve conflicting values before enabling uniqueness. Do not change an established integration key without coordinating its writers and consumers.

Uniqueness is scoped to this field’s values. It does not prove that BILL-1042 and BILL-9999 represent different real-world companies. Duplicate-management rules and data ownership still matter. A stable key makes matching explicit; it does not replace data stewardship.

Prepare one existing record and one new record

In the sandbox, create or identify a non-sensitive test Account named Harbor Training with Billing Customer Key BILL-1042.
If you are backfilling keys onto existing Accounts, match them using trusted Salesforce record IDs and an approved source-to-Salesforce mapping. Do not first run an upsert against empty key fields and expect it to recognize existing companies by name.
Prepare the two-row file below. BILL-1042 is the known update; BILL-2099 must have no existing match.
Export the existing test record and the fields you intend to change. Save the original input and mapping with the test notes.

BillingCustomerKey,Name
BILL-1042,Harbor Training Updated
BILL-2099,Canyon Training New

The expected outcome is one updated Account and one new Account. Record the existing Account’s Salesforce ID so you can prove that the update kept its identity.

Run the Data Loader upsert deliberately

Open Data Loader and authenticate to the sandbox using your organization’s approved method. Confirm the destination before proceeding.
Select Upsert, choose Account, and select the test CSV.
Choose Billing_Customer_Key__c as the matching field. This selection controls the upsert identity; simply including the column is not sufficient.
Map BillingCustomerKey to Billing_Customer_Key__c and Name to Account Name. Exclude other fields that you do not intend to modify.
Choose a location for the success and error CSV files, review the operation, and execute the test.
Inspect both results and the actual Salesforce records. Confirm the existing ID was updated and the new key was inserted once.

For this simple load, there are no related-object mappings. Associating a child to a parent by the parent’s external ID is a separate matching decision. Review Salesforce’s related-record guidance before extending the job to Contacts or other child records.

Test a rerun and an intentional mistake

Run the same two rows again in the sandbox. With the same unique keys, the record identities should remain the same. Verify that there is still exactly one Account for each key, rather than relying on a completion message.

Next, use a separate test row with a deliberately misspelled key. Observe that a key with no match is eligible for insertion if the record otherwise passes requirements. This demonstrates why an update-only business process should use an update operation with known Salesforce IDs, rather than assuming Data Loader upsert will refuse new customers.

A repeatable record match is not a promise that repeated saves have no side effects. Review the flows, triggers, notifications, and downstream integrations that your org may run during a load. Test those effects separately with the relevant owners.

Reconcile before retrying

Review the success and error files together. Separate failed rows from completed rows and investigate their actual error messages. Duplicate key values, required fields, access, duplicate rules, and automation can each require a different correction. Never silently change a rejected key just to make the load pass.

If multiple existing records share a non-unique external-ID value, resolve the ambiguity before retrying; do not guess which record should win. Salesforce’s external-ID REST documentation likewise distinguishes no match, one match, and multiple matches, with multiple matches producing an error instead of selecting an arbitrary record.

For production, retain the source file, destination, selected matching field, field map, backup, result files, and reconciliation totals. Assign an owner for key changes and failed rows. These records make the next rerun understandable and recoverable.

Official Salesforce references

External ID versus Unique settings — separate matching and uniqueness responsibilities.
Insert, Update, or Delete Data Using Data Loader — upsert matching, mappings, and result files.
Import Related Records with an External ID — parent-key mapping and backfilling existing records.
REST: Upsert Records by External ID — match outcomes and API-specific behavior.
Common Data Loader Errors — access and duplicate-value troubleshooting.

Published November 6, 2026. Official references checked on this date. Example names, keys, and fields are fictional. Verify your org’s permissions, automation, and import settings before production use.