How to build lead deduplication and merge

What matters here

• Exact email match finds the easy duplicates. The expensive ones differ by a plus-address, a nickname or a job change.
• Survivorship is per field, not per record. Keep the newest phone, the human-entered title and the richest firmographics, whichever side they came from.
• Never lose activity. Tasks, emails, campaign membership and opportunities all move to the survivor, or the merge destroys the reason to merge.
• An owner change is a business decision, not a merge side effect. Flag it instead of doing it quietly.
• Merges must be reversible for a window. The first month of any dedupe rollout produces merges somebody will want back.

Who this is for

You run revenue operations or data operations. The CRM has duplicates arriving faster than anybody can clear them, and the last attempt at a bulk merge is still remembered. What you want is detection you can tune and merges you can defend.

How it works in practice

Everything that sits between two records existing and one surviving.

1. 1

   Detection runs on a scored rule set

   Exact email, normalised email, name plus company, name plus phone. Each rule carries a confidence, not a verdict.

2. 2

   High confidence merges automatically, the rest queue

   The middle band goes to a person. Auto-merging a 0.8 match is how you lose a record somebody needed.

3. 3

   Survivorship is decided field by field

   Newest phone, human-entered title, richest firmographics, earliest created date. Not whichever record is older.

4. 4

   All activity moves to the survivor

   Tasks, emails, campaign memberships, opportunities and attachments. Nothing is left pointing at a deleted id.

5. 5

   Owner changes are flagged, never silent

   If the survivor has a different owner, that is surfaced for a decision rather than applied quietly.

6. 6

   The merge is reversible for thirty days

   Both original records are retained, so a bad merge is an undo instead of a reconstruction.

Paste these into Claude Code or Codex with the Tray Headless plugin installed. Each stage runs on its own. The systems named in them are the worked example rather than a requirement, and every prompt says so.

Once per project, run /tray-workflows:set-workspace to pick the workspace these build in. Point it at a sandbox first.

1. 1

   Set up, then learn the real object model

   Merging without knowing what points at a record is how history disappears.

   Headless skills build-workflow

   Copy

   Use build-workflow. The systems in play are Salesforce, or whatever we
   run in those seats.
   
   I need Lead and Contact fields with types, plus every object that carries
   a lookup to them: Task, Event, CampaignMember, Opportunity, Attachment,
   and any custom object. Merging without that list is how activity history
   disappears.

2. 2

   Detect on several rules, each with a score

   Exact email finds the easy ones. The costly duplicates are not exact.

   Headless skills build-workflow tray-patterns

   Copy

   Use build-workflow to build detection. Run these rules, each producing a
   confidence:
   
     Exact match on lower(email)                          1.00
     Normalised email, plus-addressing and dots stripped  0.95
     Same name and same company, normalised               0.85
     Same name and same phone in E.164                    0.85
     Same company and same phone, different name          0.60
   
   Take the highest score per candidate pair. Above 0.90 merges
   automatically, 0.70 to 0.90 goes to a review queue, below that is not a
   duplicate.
   
   Run it on insert and as a nightly sweep, because duplicates arrive in
   list imports rather than one at a time.

3. 3

   Decide survivorship field by field

   The part that decides whether people trust the merge.

   Copy

   Do not pick a winning record. Decide per field:
   
     Email          the one on the record with more activity
     Phone          the most recently modified non-empty value
     Title          human-entered beats enriched, newest beats oldest
     Company        the enriched value if both are present
     Firmographics  the most complete set, not the newest
     Created date   always the earliest, so tenure is not reset
     Source         the earliest, so first-touch attribution survives
   
   Show me the resolved record before writing when it goes through the
   review queue, with each field labelled by which side it came from.

   Keeping the earliest created date and source is what stops deduplication quietly destroying first-touch attribution reporting.

4. 4

   Move every piece of history

   A merge that loses activity has removed the reason to merge.

   Headless skills tray-gotchas

   Copy

   Use tray-gotchas, then reparent everything to the survivor:
   
     Tasks and Events, with their original timestamps intact
     Campaign memberships, deduplicated so one person is not counted twice
        in the same campaign
     Opportunities, and stop the merge entirely if both records have open
        opportunities, because that is a conversation not an automation
     Attachments and notes
     Any custom object with a lookup
   
   Verify nothing points at the losing record before it is retired, and keep
   both originals for thirty days so a bad merge is an undo.

5. 5

   Never reassign an owner quietly

   Ownership is commercial, and silent changes destroy trust in the whole system.

   Copy

   If the two records have different owners, do not resolve it in code.
   
   Keep the survivor owner, flag the conflict, and notify both owners with
   the two records and the activity on each. A human decides.
   
   Report weekly: duplicates detected by rule, auto-merge rate, review queue
   size and age, owner conflicts raised, and merges reversed. The reversal
   count is the honest measure of whether the thresholds are right.

6. 6

   Validate, then hand it over

   So thresholds move on evidence, not by ticket.

   Copy

   Run the per-step schema checks and the whole-workflow audit before this
   touches production. Start in report-only mode for a fortnight: detect and
   queue, merge nothing, and read the queue.
   
   Then open the same workflow in Tray Build so revenue operations can adjust
   the thresholds and the survivorship rules in the visual canvas.

What it connects to

Dedupe reads and rewrites the system of record, so it touches everything attached to a person.

Named systems are the ones most teams run, not the only ones that work. Each is an authentication in your Tray workspace, referenced by name, so the workflow never holds a credential. Where we have a connector page, the name links to it.

Questions people ask

Further reading

Background on the same subject, for the case rather than the build.

• Automate your way to CRM data hygiene
• The ultimate guide to automating the entire lead lifecycle

Related guides