# Merging two records

`merge_people` folds two records into one and it runs only when a person asks for it. Everything material from both sides survives — identities, stages, follow-ups, deals, demos, cases and onboarding — and afterwards every channel answers one relationship instead of two. There is no clean undo, which is the reason the decision is never automated.

- **Status:** Available
- **Audience:** both
- **In the app:** #/relationships, #/data
- **Last verified:** 2026-09-10
- **Canonical:** https://connectbyjbrh.com/docs/relationships/merging/

## The decision, and who makes it

A merge is available from a duplicate proposal and from a pair you found yourself; the proposal is a convenience, not a precondition. What both routes share is that a person reads both records and accepts. Connect will show a pair, describe what each side holds, and wait.

Treat it the way you would treat clearing a do-not-contact entry: a change whose cost is invisible for a while and then permanent. The Assistant's rights are deliberately narrower than a person's, and this is exactly the class of action where that boundary earns its keep.

## What happens when it runs

1. You accept the merge.
   - Result: One record survives and the other's material is carried onto it: identities, stages, follow-ups, deals, demos, cases and onboarding from both sides.
2. Addresses re-point.
   - Result: Every identity from the absorbed record now resolves to the surviving person, so `by_handle` sends the next message from any of those addresses to one place.
3. The assembled views change shape.
   - Result: The timeline shows both histories in one order and [customer 360](/docs/relationships/customer-360/) reads one record — which is why entries appear to arrive all at once.
4. The relationship summary is regenerated.
   - Result: The story is written from the records, so it re-reads the merged set rather than stitching two old summaries together.

> **Note** Nothing is deleted to make room. The point of the operation is preservation, and [what a merge preserves](/docs/relationships/merge-safety/) names each kind of record and says what happens when both sides hold one.

## What you cannot get back

- **The separation itself.** Two histories become one history; unpicking which message belonged to which original record is manual work over the underlying rows.
- **The certainty of an unmerged pair.** Before a merge you have two clean records and half a history each; afterwards you have one record you must trust.
- **A wrong merge, cheaply.** Merging two colleagues at one customer blends two humans. The repair is by hand and the damage is quiet: replies stay polite and start referring to things the reader never said.

That asymmetry is the whole design argument. An unmerged duplicate is a visible, harmless inconvenience — each channel answers with what it knows. A wrong merge is an invisible, harmful one. So detection proposes, a person decides, and the product declines to be clever on your behalf.

## Before you accept

**Read both sides** — Identities first, then the most recent conversation on each. A shared employer is context, not proof.
**Check open work** — Cases, demos, opportunities and follow-ups all carry over; you want to know what the survivor will be holding.
**Prefer the record with the richer history as the survivor** — Both sides are preserved either way, but the surviving record is the one people will search for by name.
**Stop if you are unsure** — An ignored proposal costs nothing. There is no queue draining behind you and no deadline on the decision.

The end-to-end version of this, from the proposal appearing to the merged record answering on every channel, is [merging duplicate people, end to end](/docs/workflows/duplicate-merge/).

## Questions

### Can I undo a merge?

There is no clean undo. The records are folded together and separating them again means working through the underlying rows by hand. Because of that, the operation is never run automatically and never in bulk over a list nobody has read.

### Which record survives?

One record survives and absorbs the other's material; nothing material from either side is discarded. Choose the record whose name and identities people will search for, since that is what colleagues will be typing months later.

### Does a merge notify the customer?

No. It is an internal change to how records are organised. Nothing is sent, and the customer sees no difference — except that the next reply they get is written with the whole relationship in view rather than half of it.

## Related

- [Duplicate detection](https://connectbyjbrh.com/docs/relationships/duplicates/)
- [What a merge preserves](https://connectbyjbrh.com/docs/relationships/merge-safety/)
- [Identities](https://connectbyjbrh.com/docs/relationships/identities/)
- [Merging duplicate people, end to end](https://connectbyjbrh.com/docs/workflows/duplicate-merge/)
- [Deciding whether two records are one person](https://connectbyjbrh.com/docs/workflows/identity-merge-decision/)
- [Connect Assistant](https://connectbyjbrh.com/docs/assistant/)

## What this page is based on

- `docs-source/sources/CHANNELS.md` §5 — `merge_people` is a human decision
- `docs-source/sources/GENERAL.md` §8 — the Assistant's narrower rights
- Connect capability registry (docs-source/facts.py)