Upsert

Upsert determines if a key of a record is mapped and performs either an update or an insert operation in response. This functionality, available for both bulk and row-by-row operations, is determined by the Dynamics 365 version you are running:

Note: The Upsert operation is not supported by Microsoft Dynamics CRM on-premise deployments, and on CRM Online 2015 and below. Support for Upsert began as of the CRM Online 2015 Update 1 release. Using the Upsert operation with a version of Microsoft Dynamics CRM where Upsert is not supported causes duplicate records to be created if a record already exists. Use Update/Insert instead. See Use Upsert to insert or update a record on the Microsoft Developer Network for more information.

• Dynamics CRM 7.1 and Later — Provides upsert functionality in a single call that performs either an update or an insert, based on the primary and alternate keys:
  • Update — Performed if one of the following applies:
    • A primary or alternate key is mapped to the target.
    • A match is found in the target.
  • Insert — Performed if one of the following applies:
    • No primary or alternate key is mapped to the Dynamics 365 target.
    • A primary or alternate key is mapped to the Dynamics 365 target, but the key value in the target is NULL or empty.
    • A primary or alternate key is mapped to the Dynamics 365 target, but no key value match is found.
• Dynamics CRM 7.0 and Earlier — Provides upsert functionality with a seek followed by either an update or an insert, based on the primary key:
  • Insert — The primary key is not mapped.
  • Update — The primary key is mapped and a matching primary key is found.
  • Neither — Primary key is mapped but no matching primary key is found. A Success(0) is returned.

Note: The overiddencreatedon field is not supported for Upsert operations, only for Create operations.