Salesforce upsert vs update: what each write does

What happens on no match, one match or several, and which field to match on: Salesforce upsert vs update, beside other CRMs.

Salesforce: 1 of 63 tools

  • SalesforceAccount, Contact and LeadWorks in our connector: up to 200 records per request; only the fields sent change; matches an existing record on a unique field, or creates one. Salesforce's own upsert matches on one field: the record ID, an external ID field, or on standard objects a field marked idLookup. No match creates a record, one match updates it, and several matches return an error and write nothing.
    Create
    Works in our connector: up to 200 records per request.
    Update
    Works in our connector: up to 200 records per request; only the fields sent change.
    Bulk jobs
    Not built yet.
    Custom fields
    Works in our connector: writes existing custom fields. Creating new fields is not built yet.
    Delete
    Works in our connector: up to 200 records per request.

    Source: our own records, trailhead.salesforce.com: apex database dml (opens in a new tab)

Photo of Utku Zihnioglu

By

ยท CEO & co-founder

Updated Nov 11, 2026

Shorter page: the tool first, the answer in a few lines.

Salesforce upsert vs update comes down to one question: what should happen when the record is not there? An update finds each record by its Salesforce record ID and never creates one, so a missing record returns an error. An upsert matches each record on one field: no match creates a record, one match updates it, and several matches return an error and write nothing.

The matrix above shows what our connector writes to Salesforce, beside the other tools we connect. A cell that says a write is not built yet is about our connector, not the tool's own API.

Which one to use

  • The records came out of Salesforce. Keep the record ID column and update. A record deleted since the export errors instead of coming back.

  • The records come from a system with its own key. Create a custom field in Salesforce, mark it External ID and unique, fill it on the records you already have, then upsert on it.

  • A cleanup job. Update. When a job is meant to change records that exist, an error on a missing record tells you something; an upsert creates a duplicate that turns up weeks later in a report.

Pick the match field with care

An idLookup field is not necessarily unique. When two records share a value, the upsert for that value stops with an error, so a unique External ID field is the usual choice. If you only have names and email addresses, find and merge duplicates before the load.

Neither write merges records for you. An upsert writes the fields you send to the one record it found, and the fields you leave out keep their values.

The matching rule follows Trailhead's Apex DML module.

What to do next

Test a handful of records first and read each result: created, updated or an error. Every write also spends API calls, so check the REST API limits before a large load.

In Oneprofile, an export to Salesforce offers create, update, or create or update, matched on the field you pick. A test run asks Salesforce what a real run would do and writes nothing.

Salesforce upsert vs update: questions

What is upsert in Salesforce?

One write that updates a record when it finds a match and creates one when it does not. Salesforce matches on a single field: the record ID, a field marked External ID, or on standard objects a field marked idLookup.

How do I upsert with the Salesforce REST API?

Send a PATCH to the object, the External ID field and its value, with the fields to write in the body. Salesforce answers 201 when it created the record and 200 when it updated one (204 in API version 45.0 and earlier). sObject Collections takes many records per call.

Can the Salesforce Bulk API upsert?

Yes. A Bulk API 2.0 ingest job takes the upsert operation and the External ID field to match on, then loads a CSV. Bulk upsert jobs are not built yet in our Salesforce connector, which upserts through the REST API.

Does HubSpot have an upsert API?

Yes. HubSpot's batch upsert takes an idProperty, email for contacts or a custom unique property, updates the records that exist and creates the rest. Partial upserts by email are not supported; by a custom unique property they are.

About this article

Photo of Utku Zihnioglu

Utku Zihnioglu

CEO & co-founder

Serial entrepreneur who built infrastructure companies handling billions of requests. Now leads engineering at Oneprofile, which finds the people worth talking to, researches each one, and follows up until they reply.

Drafted with AI from our product docs and code. Utku Zihnioglu answers for what it says.

Write enriched records back to Salesforce

Create, update or upsert from Oneprofile, matched on the field you pick, after a test run that writes nothing.

Free plan: 200 credits a month, 3 integrations, no card

Write enriched records back to Salesforce

Create, update or upsert from Oneprofile, matched on the field you pick, after a test run that writes nothing.

Free plan: 200 credits a month, 3 integrations, no card