Merging duplicate contacts

Why duplicates happen

CRM dedupes on email first, then phone. A duplicate typically slips through in one of these cases:

• The same person signs up twice with two different emails (personal and work).
• An old contact had an outdated phone number; a new interaction created a second record with the current one.
• A CSV import from an old CRM carried over legacy typos (jane@examle.com vs jane@example.com).
• A contact was created manually with just a name, then later walked in and was auto-created via Queue with a phone number.

Find duplicates

From CRM > Contacts > Duplicates, CRM shows likely-duplicate pairs ranked by match confidence. The matcher looks at:

• Email similarity (exact, close via Levenshtein distance, and domain+localpart variations).
• Phone number (normalized to E.164, including common formatting variants).
• First + last name similarity combined with either a shared account or a shared tag.

Pairs with a confidence score above 90% are auto-flagged for merge; below 90% they're suggested but require human confirmation.

How a merge works

Pick the “keeper” record — the one that will survive. Click Merge into keeper. CRM:

1. Copies non-empty fields from the duplicate into empty fields on the keeper.
2. Reattaches every activity entry, deal, account link, tag, and campaign history from the duplicate to the keeper.
3. Adds both records' email and phone values as additional identifiers on the keeper — so a future lookup by either one still finds the merged contact.
4. Publishes crm.contact.merged on platform_api with winner_id and loser_id, which subscribed apps use to reconcile any foreign keys they held.
5. Deletes the duplicate (soft-delete, 30-day retention in case you need to undo).

Field conflicts

If both records have a non-empty value for the same field (say, different job titles), CRM asks you to pick which one to keep before completing the merge. The other value is preserved on a “previous value” attribute so you can see what was overwritten.

What happens downstream

• Queue and Reservations update their own contact references the next time they see the crm.contact.merged event — no manual cleanup needed.
• Printing history keeps the original contact reference on old jobs (for audit) but new jobs will render from the merged keeper record.
• Campaigns and activity logs deduplicate automatically — two sends to the same merged contact from the same campaign now register as one.

Bulk merge via API (Admin tier)

For large cleanup jobs, there's a bulk-merge endpoint on platform_api. Supply a JSON list of {winner_id, loser_id} pairs and the merges run as a background job with a progress webhook. Handy after a large CSV import that you know carried duplicates.

Undo

For 30 days after a merge, the duplicate record is soft-deleted and can be restored from Contacts > Trash. After 30 days the soft-delete is purged and the merge becomes permanent. If an app subscribed to crm.contact.merged already updated its references, restoring the loser leaves those apps pointing at the keeper — not a disaster, but a thing to know.