Merge table rows using the Web API

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

Note

Only the following entity types can be merged:

• account

• contact

• lead: Available with Dynamics 365 for Sales

• incident : Available with Dynamics 365 for Service

  See Merge behavior for incident

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	More 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 moves any useful data from the Subordinate record to the Target record. Any existing data in the Target record aren't 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.

Request:

POST [Organization URI]/api/data/v9.2/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
}

Important

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.

Response:

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 isn't 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 reparenting related records, that the merge operation performs.

  If the user merging records doesn't have privileges for all the actions contained within the merge operation, the merge operation 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