I am creating a contact using CiviCRM API, what I have noticed that the duplicate checking looks inaccurate compared to the check done when entering new contacts via the User Interface.

Under the CiviCRM API, it's only a match if the given parameters are exactly the same like "John Smith of [email protected]" does not match "Johnathan Smith of [email protected]", for example, but in the UI, simply entering a matching e-mail address throws a warning.

Is there a way to make the CiviCRM API dupe check behave more like the UI ?

I am passing the parameter dupe_check = true. The complete call is:

$result = civicrm_api3('Contact', 'create', 
          array( 'sequential' => 1,
                 'contact_type' => "Individual",
                 'first_name' => "raj", 
                 'last_name' => "l", 
                 'dupe_check' => 1, 
                 'api.Email.create' => array('email' => "[email protected]"), )
  • Are you using the duplicatecheck action from the Contact api? Maybe you can add some sample code? Nov 17, 2016 at 12:15
  • Yes i am passing dupe_check = true. $result = civicrm_api3('Contact', 'create', array( 'sequential' => 1, 'contact_type' => "Individual", 'first_name' => "raj", 'last_name' => "l", 'dupe_check' => 1, 'api.Email.create' => array('email' => "[email protected]"), ));
    – MH9
    Nov 21, 2016 at 5:30
  • Note: in most cases, you probably want to pass check_permissions: 0 in a call to api.Contact.create. The reason for this is that permissions are taken into account when checking for dupes, so an anonymous user who fills out a form is never going to get matched unless you have very permissive configs. Further note: client-side requests have check_permissions forced to 1, so you may have to get creative if you aren't working in PHP. Jun 30, 2017 at 21:48

2 Answers 2


There are different sets of deduplication rules, and you can create your own. They may be:

  • Unsupervised- are used automatically when contacts are created in certain ways, such as through imports, event registrations and profiles
  • Supervised- are used to check/warn of possible duplicates when creating new contacts in the UI
  • General- you can use these at your leisure from the "Find and Merge Duplicate Contacts" page

What you're seeing in the API is probably only the Unsupervised rule, which should be deliberately strict. What you're warned about in the UI will be the Supervised rule.

The docs: https://docs.civicrm.org/user/en/4.6/common-workflows/deduping-and-merging/

  • 1
    We even effectively disabled the unsupervised rule, by setting it to match on the contact ID. We have a signup process consisting of multiple Drupal Webforms, and together with unsupervised dedupe (I am informed, this is from before I worked here) it presented a possible information disclosure.
    – DaveFF
    Nov 22, 2016 at 16:11

I did some research in the code. When you use the contact API, the default Unsupervised rule for the Contact Type. This rule is configurable in the Contacts -> Find and Merge Duplicate Contacts screen.

Update: The contact has another option. You can use the duplicatecheck method. But it cannot be tested in the API explorer. The following code returns the contact_ids found deduplication rule 4 (Checking on email for Individuals).

$result = civicrm_api3('Contact', 'duplicatecheck', array(
     'return' => array("display_name"),
     'dedupe_rule_id' => 4,
     'check_permission' => FALSE,
     'match' => array(
        'contact_type' => 'Individual',
        'email'        => '[email protected]'
  • 1
    Actually you can test it in the API Explorer. Just add a parameter other as "match" and then you can put in the parameters like this: {"contact_type":"Individual","email":"[email protected]","last_name":"lastname","first_name":"firstname"}
    – Sleewok
    Nov 30, 2016 at 19:16

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service and acknowledge you have read our privacy policy.

Not the answer you're looking for? Browse other questions tagged or ask your own question.