# Deciding whether two records are one person

Connect proposes; a person decides. Duplicate detection puts forward candidates with the evidence for each, and `merge_people` runs only when somebody says yes — because joining two humans' histories wrongly costs far more than carrying a duplicate for another week. The merge preserves identities, stages, follow-ups, deals, demos, cases and onboarding from both records.

- **Status:** Available
- **Audience:** both
- **In the app:** #/relationships
- **Last verified:** 2026-09-10
- **Canonical:** https://connectbyjbrh.com/docs/workflows/identity-merge-decision/

## Why this is not automatic

The two errors are not symmetrical. A duplicate that survives another week is untidy: two records, two partial histories, an answer that misses context. A wrong merge is a different category — two real people's conversations, deals and commitments now sit on one record, every future answer is grounded in a mixture of them, and unpicking it means knowing which of two histories each row came from.

So detection is a proposal, not an action. `duplicates` puts candidates forward with what makes them candidates; `merge_people` is a human decision, and it stays one.

## The stage chain

1. Trigger — a message arrives from an unrecognised address, a record is created, or somebody opens the duplicates view and asks.
2. User or external event — often the customer's own doing: they wrote from a personal address, changed employer, or rang from a number nothing had seen.
3. Authentication and workspace resolution — candidates are only ever drawn from one workspace. Two people in two workspaces are never candidates for each other, whatever they look like.
4. Ingest — the identity in hand is normalised to a comparable key for its channel, so an address is compared as an address rather than as text.
5. Canonical record — an exact identity match is not a suggestion at all: it resolves, immediately, to the Person that identity belongs to. Suggestions only exist for the cases where nothing matches exactly.
6. Classification and reasoning — the remaining signals are weighed and candidates are proposed with the evidence attached, so the reviewer is reading facts rather than a score.
7. Knowledge, memory and rules — nothing here overrides identity. What Connect remembers about a person is attached to the record, and follows it through a merge rather than deciding one.
8. Autonomy and approval — the gate, and it is absolute. No autonomy setting merges records automatically; this is a decision a person makes with both records in front of them.
9. Action — `merge_people` runs. Both records' identities, lifecycle stages, follow-ups, deals, demos, cases and onboarding are preserved on the survivor.
10. Result — one person remains. Every identity that used to resolve to either record now resolves to the survivor, so the next message from any of those addresses lands in the right history.
11. Relationship, timeline and memory — the timeline becomes one sequence in the order events actually happened, which is usually the first time anyone sees the relationship whole.
12. Audit — who merged what, and when, is recorded. That matters precisely because a merge is hard to reverse.

## What the reviewer is looking at

| Question | Where the answer is | What a no looks like |
|---|---|---|
| Is this the same human? | The identities, the company, the names on each record | Two colleagues at one company with similar names |
| Do the histories agree? | Both timelines, side by side | Overlapping conversations that contradict each other |
| Is one of them a company, not a person? | The record type and its attachments | An organisation being proposed as a duplicate of an individual |
| What is owed on each side? | Open follow-ups, cases and deals on both | Commitments that would double up after the merge |

> **Note** The fourth row is worth acting on the moment a merge completes. Both sides' follow-ups survive on purpose — losing a commitment in a merge would be worse than carrying a duplicate one — so the survivor may now owe the same chase twice. Read their open follow-ups straight away.

## After the decision

- Messages from every address on either record now reach one person, so the next reply is grounded in the whole relationship.
- The Customer 360 and the timeline show one sequence rather than two partial ones.
- Open commitments from both sides are live; cancel the ones that now say the same thing twice, with a reason.
- A case or an onboarding from either record continues on the survivor, with its own history intact.
- The audit trail names who decided, which is the question asked whenever a merge is later doubted.

If the decision turns out to be wrong, the honest position is that a merge is not a reversible toggle. That asymmetry is precisely why the gate is a person and why the evidence is shown rather than summarised into a confidence number that invites a habit of clicking yes.

## Questions

### Will Connect merge two records on its own if it is confident enough?

No. Detection proposes and a person decides, at any level of similarity. The cost of a wrong merge is not comparable to the cost of a duplicate, so no threshold is treated as sufficient.

### What happens to the follow-ups on the record that disappears?

They survive on the surviving person, along with identities, stages, deals, demos, cases and onboarding. That is deliberate — and it is why the survivor can suddenly owe two similar chases.

### Can records from two workspaces be merged?

No. Candidates are only ever drawn from within one workspace. Two people in different workspaces are never proposed for each other, whatever they have in common.

## Related

- [Duplicate detection](https://connectbyjbrh.com/docs/relationships/duplicates/)
- [Merging two records](https://connectbyjbrh.com/docs/relationships/merging/)
- [What a merge preserves](https://connectbyjbrh.com/docs/relationships/merge-safety/)
- [Merging duplicate people, end to end](https://connectbyjbrh.com/docs/workflows/duplicate-merge/)
- [The same person is being chased repeatedly](https://connectbyjbrh.com/docs/troubleshooting/too-many-follow-ups/)
- [Why the machine proposes a merge and a person disposes](https://connectbyjbrh.com/research/one-person-many-channels/)

## What this page is based on

- `docs-source/sources/CHANNELS.md` §5 — `duplicates`, `merge_people` and what a merge preserves
- `docs-source/sources/CHANNELS.md` §5 — `people.add_identity` and `value_key(kind, value)`
- `docs-source/sources/GENERAL.md` §10 — workspace isolation
- Connect capability registry (docs-source/facts.py) — `duplicate_merge`, `cross_channel_identity`