Identity stitching

UMAP360 builds one profile per person by stitching together the identity signals on the events you send — across sessions, devices, and the anonymous-to-known transition. You don't call a merge API for the anonymous-to-known transition; you send consistent signals and the platform resolves them. (An admin POST /v1-profiles/merge endpoint does exist, for manually combining two existing profiles.)

The signals

Identity is resolved from four signals on each event:

Signal	Where it comes from
`anonymousId`	Top-level field — a stable per-device/browser id.
`userId`	Top-level field — set once a visitor is known.
Email	`traits.email` (typically sent on `identify`) or `properties.email`.
Phone	`traits.phone` or `properties.phone` (normalised to digits + leading `+`).

The platform's identity resolver links events that share these signals into a single profile. A device fingerprint can act as an additional signal, but only when the visitor has consented — see Consent.

The pattern

Always send a stable anonymousId. Generate it once per browser/device and reuse it on every event. This is what ties a visitor's events together before they're known.

identify when the visitor becomes known. Send an identify event with the userId and any traits you have (email, phone, name):

{
  "type": "identify",
  "messageId": "msg_1001",
  "timestamp": "2026-06-08T10:00:00.000Z",
  "anonymousId": "anon_xyz789",
  "userId": "user_456",
  "traits": { "email": "user@example.com", "name": "Asha R." }
}

Keep the same anonymousId across the transition. Because the identify above carries both the existing anonymousId and the new userId, the anonymous history is linked to the known user — the pre-signup page views and the post-signup activity become one profile.

Don't rotate the anonymousId on login

The single most common stitching mistake is generating a fresh anonymousId after the user logs in. That orphans the pre-login history. Persist one anonymousId per device and let identify connect it to the userId.

How resolution works

Resolution happens server-side. When events share a signal — or when an identify carries both an anonymousId and a userId — the resolver links them into one profile, so a visitor's pre-signup and post-signup activity end up under the same profile. Each event records which signal resolved it (resolution_method), and different signals carry different confidence / stability scores — visible per-signal through the identities endpoint below.

You can inspect a profile's full signal graph through the Profiles API with a read key (uk_read_):

GET https://YOUR_PROJECT_REF.supabase.co/functions/v1/v1-profiles/{id}/identities

The response groups the profile's signals (user_id / email / anonymous_id), fingerprints, and click_ids — see the Profiles API for the full endpoint set.

Confirm stitching worked. After an identify (or an alias merge), look the person up — e.g. GET /v1-profiles/search?email=user@example.com or GET /v1-profiles/{id}/identities — and check that the pre- and post-identify signals resolve to a single profile.

identify vs alias (and group)

For the common anonymous→known transition, send identify with the same anonymousId plus the userId — that's the simplest path and what this guide recommends. alias is for linking two distinct identities: an alias whose previousId differs from both userId and anonymousId now triggers a real server-side merge of the two profiles (a self-alias, or previousId equal to the current anonymousId, is handled by ordinary resolution instead). Because previousId drives a merge, a junk previousId is rejected per-event. group is not yet active — group events are stored but groupId isn't used to associate profiles. See Event ingestion.

Profiles API — list, search, inspect, and merge the profiles your signals resolve into.
Attribution — how a profile's click-IDs and first/last touch drive conversion forwarding.
Consent — when a fingerprint is allowed to act as an identity signal.

Last updated 2026-06-10

The signals

The pattern

How resolution works

Next