Detect duplicate data using the Web API

You can detect duplicate table rows of an existing row in order to maintain integrity of data. For detailed information about detecting duplicate data using code, see Detect duplicate data using code

Detect duplicates during Create operation

Use the MSCRM.SuppressDuplicateDetection request header with a POST request to detect creation of a duplicate record of an existing record. The value assigned to MSCRM.SuppressDuplicateDetection header determines whether the Create or Update operation can be completed:

  • true – Create or update the record, if a duplicate is found.
  • false – Do not create or update the record, if a duplicate is found.

Use preference header MSCRM.SuppressDuplicateDetection and set its value to false in the Web API request.

Note

Make sure there are appropriate duplicate detection rules in place. Dataverse includes default duplicate detection rules for accounts, contacts, and leads, but not for other types of records. If you want the system to detect duplicates for other record types, you'll need to create a new rule.
- For information on how to create a duplicate detection rule using the UI, see Set up duplicate detection rules to keep your data clean.
- For information on creating duplicate detection rules using code, see Duplicate rule tables

Example: Detect duplicates during Create operation using the Web API

The following example shows how to detect duplicates during Create and Update operations using MSCRM.SuppressDuplicateDetection header in Web API request.

Request:

POST [Organization URI]/org1/api/data/v9.2/leads HTTP/1.1
If-None-Match: null
OData-Version: 4.0
OData-MaxVersion: 4.0
Content-Type: application/json
Accept: application/json
MSCRM.SuppressDuplicateDetection: false


{
    "firstname":"Monte",
    "lastname":"Orton",
    "emailaddress1":"monteorton@example.com"
}

If a lead record with the same emailaddress1 attribute already exists, the following Response is returned.

Response:

HTTP/1.1 500 Internal Server Error  
Content-Type: application/json; odata.metadata=minimal  
OData-Version: 4.0

{
    "error": {
        "code": "0x80040333",
        "message": "A record was not created or updated because a duplicate of the current record already exists."
    }
}

Assign value true to MSCRM.SuppressDuplicateDetection header to allow creation of a duplicate record.

Detect duplicates during Update operation

Set the value of MSCRM.SuppressDuplicateDetection header to false in your PATCH request to avoid creation of a duplicate record during Update operation. By default, duplicate detection is suppressed when you are updating records using the Web API.

Example: Detect duplicates during Update operation using the Web API

The example shown below attempts to update an existing lead entity record which includes the same value of emailaddress1 attribute as an existing record.

Request:

PATCH [Organization URI]/api/data/v9.2/leads(c4567bb6-47a3-e711-811b-e0071b6ac1b1) HTTP/1.1
If-None-Match: null
OData-Version: 4.0
OData-MaxVersion: 4.0
Content-Type: application/json
Accept: application/json
MSCRM.SuppressDuplicateDetection: false
If-Match: * 

{
    "firstname":"Monte",
    "lastname":"Orton",
    "emailaddress1":"monteorton@example.com"
}

Response:

HTTP/1.1 500 Internal Server Error  
Content-Type: application/json; odata.metadata=minimal  
OData-Version: 4.0

{
    "error": {
        "code": "0x80040333",
        "message": "A record was not created or updated because a duplicate of the current record already exists."
    }
}

See Also

Detect duplicate data using the SDK for .NET