Merge table rows using the Web API

When you find duplicate records you can combine them into one using the Merge Action.


Only the following entity types can be merged:

Merge action

Merge is an unbound action that accepts four parameters:

Name Type Description Optional
Target crmbaseentity The target of the merge operation. No
Subordinate crmbaseentity The entity record from which to merge data. No
UpdateContent crmbaseentity Additional entity attributes to be set during the merge operation. Yes
PerformParentingChecks Boolean Indicates whether to check if the parent information is different for the two entity records. No

Merging will move any useful data from the Subordinate record to the Target record. Any existing data in the Target record will not be overwritten. Then the Subordinate record is deactivated. To perform this operation the caller must have privileges and access rights to both the records identified as the Target and Subordinate.

Use a POST request to send data to merge records. This example merges two account entity records while updating accountnumber property of the record that will remain after the merge.


POST [Organization URI]/api/data/v9.0/Merge HTTP/1.1
Content-Type: application/json; charset=utf-8
OData-MaxVersion: 4.0
OData-Version: 4.0
Accept: application/json

  "Target": {
    "name": "Account 1",
    "accountid": "bb8055c0-aea6-ea11-a812-000d3a55d474",
    "@odata.type": "Microsoft.Dynamics.CRM.account"
  "Subordinate": {
    "name": "Account 2",
    "accountid": "c38055c0-aea6-ea11-a812-000d3a55d474",
    "@odata.type": "Microsoft.Dynamics.CRM.account"
  "UpdateContent": {
    "accountnumber": "1234",
    "@odata.type": "Microsoft.Dynamics.CRM.account"
  "PerformParentingChecks": false


Because the Target, Subordinate, and UpdateContent property types are not explicitly defined by the parameter, you must include the @odata.type annotation to specify the type.


HTTP/1.1 204 No Content
OData-Version: 4.0

Merge behavior for incident

The merge behavior for incident (case) table is different from account, contact, or lead tables.

  • The UpdateContent parameter data is not used.

  • Merge is performed in the security context of the user

    Merge operations for other tables are performed with a system user security context. Because incident merge operations are performed in the security context of the user, the user must have the security privileges to perform any of the actions, such as re-parenting related records, that are performed by the merge operation.

    If the user merging records doesn't have privileges for all the actions contained within the merge operation, the merge operation will fail and roll back to the original state.

See also

Use Web API actions
Merge duplicate records
MergeRequest Class
Administration Guide: Merge data
Dynamics 365 for Service: Merge cases