Duplicates

A duplicate is a pair of contacts that Carom suspects are the same person, because they share an email address, a name, or both. Carom finds these pairs on its own as mail arrives. Use this resource to see the suspects for a contact, then either merge them or reject the pair so Carom stops suggesting it.

A contact with at least one open pair has has_duplicates set to true. A pair is listed only when both of its contacts are visible to your key, and working with a contact’s duplicates requires your key’s user to be able to edit that contact.

#The duplicate object

One suspected pair, seen from the contact you asked about. suspected_duplicate is the other contact in the pair. The duplicate’s own id is what Reject a duplicate and Restore a duplicate take; it is not a contact id.

Attributes

  • idstring · uuid

    Unique identifier for the pair.

  • namestring · nullable

    A label for the pair: the name the two contacts share, or for an email match, the name of one of them. When neither contact has a name, Email: followed by the shared address.

  • match_typestring · nullable

    What the two contacts have in common.

    emailnameboth
  • suspected_duplicatecontact · nullable

    The other contact in the pair, with its email addresses.

The duplicate object 
{
  "id": "6d1f3b8e-9a2c-4e7d-b5f1-3c8a0e6d2b49",
  "name": "Priya Natarajan",
  "match_type": "name",
  "suspected_duplicate": {
    "id": "4c7a1e9d-3b5f-4d2e-8a6c-0b9d7e5f3a21",
    "name": "Priya Natarajan",
    "contact_type": "connection",
    "global": false,
    "email_addresses": [
      {
        "id": "7e2b5c8d-9f1a-4b3e-8d6c-4a0f2e9b1c75",
        "value": "pnatarajan@gmail.example",
        "primary": true
      }
    ],
    …
  }
}
get/contacts/{contact_id}/duplicates Read key

#List a contact’s duplicates

Returns every open pair that includes the contact in one response; the list isn’t paginated. Rejected pairs are left out.

Path parameters

  • contact_idstring · uuidrequired

    The contact’s id.

Returns

  • collectionobject

    The contact’s open pairs.

    Show 2 child attributesHide child attributes
    • recordsarray of duplicates

      Every open pair that includes the contact.

    • total_resultsinteger

      Number of pairs in records.

Errors

  • 403permission_deniedThe contact is visible to your key, but your key’s user can’t edit it.
  • 404record_not_foundNo contact with that id is visible to your key.
get/contacts/{contact_id}/duplicates 
curl https://api.carom.io/contacts/1f3c9a52-7b0e-4d4a-9c1e-2a6f0d8b3e41/duplicates \
  -H "Authorization: Bearer $CAROM_API_KEY"
Response200 
{
  "collection": {
    "records": [
      {
        "id": "6d1f3b8e-9a2c-4e7d-b5f1-3c8a0e6d2b49",
        "name": "Priya Natarajan",
        "match_type": "name",
        "suspected_duplicate": {
          "id": "4c7a1e9d-3b5f-4d2e-8a6c-0b9d7e5f3a21",
          "name": "Priya Natarajan",
          …
        }
      }
    ],
    "total_results": 1
  }
}
post/contacts/{contact_id}/duplicates/{duplicate_id}/reject Write key

#Reject a duplicate

Records that the two contacts are different people. The pair drops out of List a contact’s duplicates for both contacts and no longer sets has_duplicates. Neither contact changes. The pair stays rejected: Carom doesn’t suggest it again, even after either contact is edited. To combine the two instead, use Merge contacts.

Path parameters

  • contact_idstring · uuidrequired

    Either contact in the pair.

  • duplicate_idstring · uuidrequired

    The id of the duplicate, not the id of the suspected contact.

Returns

The ok object, {"ok": "ok"}.

Errors

  • 403permission_deniedThe contact is visible to your key, but your key’s user can’t edit it.
  • 404record_not_foundThe contact isn’t visible to your key, or no duplicate with that id includes it.
post/contacts/{contact_id}/duplicates/{duplicate_id}/reject 
curl -X POST https://api.carom.io/contacts/1f3c9a52-7b0e-4d4a-9c1e-2a6f0d8b3e41/duplicates/6d1f3b8e-9a2c-4e7d-b5f1-3c8a0e6d2b49/reject \
  -H "Authorization: Bearer $CAROM_API_KEY"
Response200 
{ "ok": "ok" }
post/contacts/{contact_id}/duplicates/{duplicate_id}/unreject Write key

#Restore a duplicate

Undoes Reject a duplicate. The pair is open again: it returns to both contacts’ duplicate lists and sets has_duplicates. Rejected pairs aren’t listed, so keep the duplicate’s id when you reject it if you may want to restore it later.

Path parameters

  • contact_idstring · uuidrequired

    Either contact in the pair.

  • duplicate_idstring · uuidrequired

    The id of the duplicate.

Returns

The ok object, {"ok": "ok"}.

Errors

  • 403permission_deniedThe contact is visible to your key, but your key’s user can’t edit it.
  • 404record_not_foundThe contact isn’t visible to your key, or no duplicate with that id includes it.
post/contacts/{contact_id}/duplicates/{duplicate_id}/unreject 
curl -X POST https://api.carom.io/contacts/1f3c9a52-7b0e-4d4a-9c1e-2a6f0d8b3e41/duplicates/6d1f3b8e-9a2c-4e7d-b5f1-3c8a0e6d2b49/unreject \
  -H "Authorization: Bearer $CAROM_API_KEY"
Response200 
{ "ok": "ok" }