Skip to main content

SF-0219 · Scenario · Medium

What are the steps to UPSERT the data in salesforce using the Data loader?

✓ Verified by Vikas Singhal · Last reviewed 5/17/2026 · Updated for Spring '26

Upsert is one of the most useful Salesforce data operations: it updates a record if it already exists, otherwise creates a new one. The key it matches on isn’t the Salesforce Id — it’s an External Id field you nominate.

Setup work first

Before you even open Data Loader, the target object needs:

  • A custom field with the External Id attribute checked.
  • Usually marked Unique as well (otherwise the upsert can’t decide which existing record to match).

Example: a Legacy_System_Id__c text field on Account, marked External Id + Unique. Your source system already knows that ID for every account, so it’s the natural matching key.

Step-by-step

  1. Prepare the CSV. Include the External Id column plus every field you want set on insert / changed on update.
  2. Launch Data Loader and click Upsert.
  3. Log in to production or sandbox.
  4. Choose the Salesforce object (e.g. Account).
  5. Choose the External Id field to use as the match key (e.g. Legacy_System_Id__c). The dropdown shows every field on the object marked as External Id.
  6. Choose the CSV file.
  7. Map columns to fields. Your External Id column maps to the External Id field. Map any other columns you want written. Save mapping as .sdl.
  8. Pick success / error directory.
  9. Click Finish. Data Loader processes the rows in batches.
  10. Review success.csv. For each row it shows the Salesforce Id of the record affected, and a Created flag (true = inserted, false = updated). The Created column is the easiest way to count how many new records came in.
  11. Review error.csv for failures.

Why teams love upsert for integrations

A nightly job from your ERP doesn’t know which Salesforce accounts already exist. Without upsert you’d have to:

  1. Query Salesforce for all Legacy_System_Id__c values.
  2. Diff against the ERP list.
  3. Run two Data Loader jobs — one Insert, one Update.

With upsert it’s one job, one CSV, and Salesforce decides per row. This is the pattern for syncing data from an external system of record.

You can also upsert a child record and reference its parent by External Id without knowing the parent’s Salesforce Id. The CSV column is named like Account.Legacy_System_Id__c, and Salesforce resolves the lookup at load time. This is what makes upsert genuinely powerful for cross-object loads.

Watch out for

  • Duplicate match. If two existing records share the same External Id value, upsert fails for that row with DUPLICATE_EXTERNAL_ID. Marking the field Unique at design time prevents this.
  • Null External Ids. Rows where the External Id is blank get treated as new records (insert).
  • Case sensitivity on text External Ids is controlled by the field’s Treat as case-sensitive setting.

Verified against: Data Loader Guide — Upserting Data, Metadata API Developer Guide. Last reviewed 2026-05-17 for Spring ‘26 release.