I recently read the REST API doc about SObject upsert endpoint, which accepts Id field as the External ID.

"Inserting New Records Using Id as the External ID"


I'm not sure why the interface exists and what benefit we can get from it. If you are sure to insert new records, it seems very equal to the sobject endpoint for record insert.

It says "This pattern is useful when you’re writing code to upsert multiple records by different external IDs and you don’t want to request a separate resource.". Unluckily I couldn't imagine the case where the situation happens.

1 Answer 1


As the documentation says, it's an "upsert," or, in other words, a combined insert/update command in one. It simplifies your programming logic, since you now only have to call one specific API instead of two different APIs (insert or update), based on having the ID available. The primary benefit is less code you need to write, since an insert and update look nearly identical. Aside from writing less code, there's no practical benefit over choosing this method and implementing insert/update commands; they have the same performance characteristics.

  • The sample of ID upsert in the doc is only for insertion with POST method, that is, the coder who writes this upsert program should assume the record to be newly created. In such situation why the coder choose ID upsert instead of usual SObject insertion ?
    – stomita
    Commented Jul 20, 2018 at 0:36
  • @stomita Again, it's meant to reduce code. Imagine you have logic like this: for(record in recordList) { upsert(record.values, record.externalIdField, record.externalIdValue); } where externalIdField could be any legal field and externalIdValue could be any arbitrary value, or null. Without this specific resource, you then have to branch off to special logic: if(record.externalIdField == 'Id' && record.externalIdValue == null) insert(record.values) else upsert(/* code from before */);
    – sfdcfox
    Commented Jul 20, 2018 at 1:13
  • even in your example the upsert() function should have a switch logic to build the endpoint URL and select HTTP method to send according to the external id field and its value. So it would not reduce anything by this special interface.
    – stomita
    Commented Jul 21, 2018 at 10:15

You must log in to answer this question.

Not the answer you're looking for? Browse other questions tagged .