Identity rules teach the platform to recognise the same person across every channel. Each rule reads a value out of an incoming widget or form signal and feeds it to a contact attribute — so a chat, a form submission and a backend conversion all collapse into one customer instead of three strangers. When two unverified traces collide, the merge review queue lets a human make the call.
Menu: Customers → Matching
Permission: comerix.crm.view to read, comerix.crm.manage to change
This page covers the two surfaces under Matching:
- Rules (
/admin/customers/identity-rules) — the tenant’s ordered mapping set that turns raw signals into identity.
- Merge review (
/admin/customers/merge-review) — the queue of ambiguous duplicate-contact candidates awaiting a decision.
Rules vs. merge reviewA rule decides what the platform pulls out of a signal and how much it trusts it. Merge review is where the low-trust matches that a rule could not resolve automatically land for a human to confirm or dismiss. See Customers for the contact records these two surfaces feed. What identity rules do
Your widget keeps emitting its event stream untouched. Identity rules sit on top of that stream and declare, per tenant, which signal carries identity. A single rule has four parts:
- When — the event name to match, or any event.
- Read — a dot-path into the raw signal payload, e.g.
props.user.email.
- Map to — the contact attribute the extracted value lands on.
- Trust — whether the value is verified, which decides if a match can auto-merge.
The dot-path is a plain a.b.c walk into the decoded envelope — no array indexing and no wildcards. A path that is missing, or resolves to a nested object rather than a single primitive value, simply does not fire.
Targets and what they do
The attribute you map to determines how identity resolution treats the value. There are four behaviours, derived automatically from the target you pick:
| Target | Kind | Behaviour |
|---|
customer_id | Anchor | Stitches sessions on sight — trusted, no verification needed |
external_ref | Anchor | Stitches sessions on sight — trusted, no verification needed |
email | Claim | Auto-merges only when verified; otherwise queues a review candidate |
phone | Claim | Auto-merges only when verified; otherwise queues a review candidate |
first_name | Name | Hints the profile name; never drives a merge on its own |
last_name | Name | Hints the profile name; never drives a merge on its own |
display_name | Name | Hints the profile name; never drives a merge on its own |
trait | Trait | Stored at contact.traits.<key>; never used for matching |
customer_id and external_ref are strong anchorsAnchors are trusted by definition — any session carrying the same anchor value collapses into one contact immediately, and verification never applies to them. Map your backend’s stable identifiers (a logged-in account id, an order-system reference) to customer_id or external_ref so authenticated visitors are recognised the instant they appear.
conversation_id is always an anchorBeyond your rules, the platform always adds the envelope’s conversation_id as an anchor. That is why an anonymous session still stitches together as one contact, and why a matching signal resolves to the session’s existing contact even before any email or phone appears.
Browse identity rules
Open Customers → Matching → Rules (/admin/customers/identity-rules). A metric strip at the top counts your active rules (of the total), anchors, claims and traits. Below it, rules are listed in evaluation order:
| Column | Meaning |
|---|
# | Precedence — the position the rule is evaluated at (lower runs first) |
| When event | The event name the rule matches, or any event |
| Read path | The dot-path read from the payload |
| Map to | The target attribute (and trait key, for traits) |
| Trust | verified / unverified for claims and anchors; name hint for name targets |
| Enabled | A toggle to pause the rule without deleting it |
No rules, no identityWith no rules defined, events still flow into each contact’s activity timeline — but nothing is extracted as identity. Add at least one rule so incoming signals start resolving to people.
Create or edit a rule
Click New rule (/admin/customers/identity-rules/new) or open an existing rule to Edit it (/admin/customers/identity-rules/{id}/edit). The editor is a four-step form on the left with a live preview pinned on the right.
1 · When this signal arrives
Choose Specific event to limit the rule to one event name, or Any event to match every signal in the stream.
| Field | Notes |
|---|
| Event name | The event to match, e.g. identify or order_completed. Must be snake_case (lowercase letters, digits and underscores). The field offers known event names as suggestions |
When to use any eventUse any event for envelope-level fields that ride along with every signal — for example context.customer_id. Use a specific event when only one event carries the value you want.
2 · Read from payload
| Field | Notes |
|---|
| Source path | A dot-path into the raw, pre-redaction signal envelope, e.g. props.user.email. Word segments separated by dots only |
3 · Map to attribute
Pick one of the eight targets from the table above. When you choose trait, an extra field appears:
| Field | Notes |
|---|
| Trait key | The key the value is stored under, at contact.traits.<key>. Letters, digits and underscores only |
4 · Trust & status
| Field | Notes |
|---|
| Mark extracted value as verified | Turn on for server-trusted sources (your backend, a confirmed login); leave off for anything a visitor typed. Applies to claims only — anchors are always trusted, and name/trait targets never merge so trust does not apply |
| Precedence | The evaluation position. Lower numbers run first |
| Enabled | Whether the rule is active |
Use the live preview
The preview on the right runs the rule you are editing against a representative sample envelope and shows exactly what would happen:
- A Fires / No match pill tells you whether the rule would match the sample event and find the path.
- The sample envelope is rendered as JSON, with the matched leaf highlighted when your path resolves.
- Extracted shows the value pulled out, the target chip it maps to, and its trust badge — or a note if the path is absent.
- A resolution outcome box explains how identity resolution would treat the result: an anchor stitches on sight, a verified claim drives an auto-merge, an unverified claim is review-gated, a name hints the profile, and a trait writes to
contact.traits.
Because the preview mirrors the server’s path reader exactly, what it shows is what production will do. Tune the path and trust toggle until the outcome reads the way you want, then save.
The merge review workflow
Open Customers → Matching → Merge review (/admin/customers/merge-review). This queue exists for one situation: an unverified claim (an email or phone typed into a public channel) that collides with an identifier already owned by a different contact. The collision is too weak to fold the records automatically, but worth a person’s confirmation.
Only ambiguous collisions land hereAnchors stitch on sight and verified claims auto-merge — neither ever reaches this queue. Merge review only holds unverified, ambiguous collisions. When the queue is empty you will see a Queue is clear state.
- Left — the pending queue, newest collisions first, each showing the colliding identifier type and value, when it was last seen, and how many times the collision has recurred (
seen N×). Click a row to inspect it.
- Right — a side-by-side comparison of the two contacts, with the colliding identifier called out in both.
The two contacts are labelled by role:
| Role | Meaning |
|---|
| Keeps identity (survivor) | The contact that already owns the colliding identifier through a verified channel — it survives the merge |
| Session | The contact that tried to claim the identifier — its identifiers and activity fold into the survivor |
Confirm or dismiss
Each candidate needs one decision:
- Confirm merge — moves the session’s identifiers and activity into the survivor, promotes the colliding identifier to verified, and deep-merges traits. The session contact is marked merged. Open the survivor’s contact first if you want to check it.
- Dismiss — keeps both contacts separate and suppresses this exact pairing in future, so it never resurfaces.
Merging is permanentConfirming a merge reassigns identifiers and the activity timeline to the survivor for good — it is hard to undo. Every confirm and dismiss is written to the audit log.
Permissions
| Action | Permission |
|---|
| View rules and the merge review queue | comerix.crm.view |
| Create, edit, enable/disable and delete rules | comerix.crm.manage |
| Confirm or dismiss merge candidates | comerix.crm.manage |
comerix.crm.view; every change — saving a rule, toggling it, deleting it, or acting on a merge candidate — additionally requires comerix.crm.manage. See Customers for the contact records these rules and merges feed. 
