Detect duplicate data using the Organization service

The Common Data Service Organization service allows you to detect duplicate records to maintain integrity of data. For detailed information about detecting duplicate data using code, see Detect duplicate data using code.


Make sure there are appropriate duplicate detection rules in place. Common Data Service 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 entities

Use RetrieveDuplicatesRequest message to detect duplicates before you create or update record

You can programmatically check whether an entity is a duplicate or will be a duplicate before creating or updating it by using the RetrieveDuplicatesRequest class.

var account = new Account();
account.Name = "Sample Account";

var request = new RetrieveDuplicatesRequest()
    BusinessEntity = account,
    MatchingEntityName = account.LogicalName,
    PagingInfo = new PagingInfo() { PageNumber = 1, Count = 50 }

var response = (RetrieveDuplicatesResponse)svc.Execute(request);

if (response.DuplicateCollection.Entities.Count >= 1)
    Console.WriteLine("{0} Duplicate records found.", response.DuplicateCollection.Entities.Count);

Use SuppressDuplicateDetection parameter to throw errors when you create or update record

If you want to have the platform throw an error when a new record you create is determined to be a duplicate record, or you update an existing record so that duplicate detection rules will be evaluated, you must use the CreateRequest or UpdateRequest classes with the IOrganizationService.Execute method and apply the SuppressDuplicateDetection parameter set to false.

The following code will throw an InvalidOperationException exception with the message A record was not created or updated because a duplicate of the current record already exists. when the following are true:

  • Duplicate Detection is enabled for the environment when a record is created or updated.
  • The account entity is has duplicate detection enabled
  • A Duplicate Detection Rule is published that checks whether the account name value is an exact match for an existing record
  • There is an existing account with the name Sample Account
var account = new Account();
account.Name = "Sample Account";

var request = new CreateRequest();
request.Target = account;
request.Parameters.Add("SuppressDuplicateDetection", false);

catch (FaultException<OrganizationServiceFault> ex)
    switch (ex.Detail.ErrorCode)
        case -2147220685:
            throw new InvalidOperationException(ex.Detail.Message);
            throw ex;

See also

Detect duplicate data using the Web API