For the complete documentation index, see llms.txt. This page is also available as Markdown.

UserPoint & Identity graph

How the user graph is organised, and when the platform decides two UserPoints are the same person.

Your goal

Understand the graph your identifiers build, and the exact conditions under which the platform merges two UserPoints - so your identity model produces the joins you want and not the ones you do not.

Expected outcome

You can predict, for a given identifier arriving on a given device, whether it creates a UserPoint, attaches to one, or merges two.

The graph

The object-graph nature of a datamart is what makes it suited to a user graph: each piece of information about a user is connected to the others in a local graph structure. The user is a node, called a UserPoint, and the user can be identified or anonymous.

These levels matter on the device side: a UserPoint can have several UserDevicePoints, and each device point can carry several UserDeviceTechnicalIds plus one set of device information. See UserDevice & UserDeviceTechnicalId.

How data finds its UserPoint

Every activity or import that carries one of the identifier properties is automatically related to the correct UserPoint. If the identifier does not already exist in the datamart, a new UserPoint is created.

This is worth restating because of what it implies: the number of UserPoints in your datamart is a consequence of your identifier strategy, not an independent quantity.

UserPoint merges

Automatic identity resolution is the platform merging two UserPoints that represent the same person.

The canonical example: you visit a site with Firefox, then come back later with Safari. At that point nothing tells the platform these are the same person, so there are two UserPoints - one carrying the UserDeviceTechnicalId from Firefox, one from Safari. If you then log in with your account on both browsers, both UserPoints become associated with a common UserAccount ID, and the platform merges them and their activities.

What triggers a merge

Merges can only be triggered by:

  • UserActivity updates - an activity arriving with several identifiers.

  • User identifier association declarations - see Resolve identities.

A merge of device points also causes a merge of UserPoints when the device points involved were linked to different UserPoints.

What a merge does

The merge results in a surviving UserPoint, to which all data related to the two previous UserPoints is migrated. All content and identifiers are regrouped under the older UserPoint, and the newer UserPoint is archived.

When a UserPoint accumulates too much

Protections exist, and seeing them on ordinary users is a signal that the identity model needs revisiting.

Hyper point

A hyper point is a preventive flag on a UserPoint that has too many identifiers linked to it. A UserPoint becomes a hyper point when the platform tries to merge UserPoints and at least one of these conditions is met:

  • The frequency of user identifier creation on this UserPoint reaches:

    • more than 10 identifiers per registry ID in 2 days,

    • more than 4 account IDs in 7 days,

    • more than 4 email hashes in 7 days.

  • More than 8 UserPoints were merged into that UserPoint in the last 14 days.

  • More than 100 user identifiers are attached to it.

Flagging is preventive: the UserPoint remains actionable in the platform.

Quarantine

The quarantine job is a monthly process that flags any UserPoint with too many objects attached - more than 10,000 activities, or more than 5,000 segments.

A UserPoint in quarantine can still be looked up in Navigator, but nothing more is added to it. The same job can free it once it drops below those limits, which typically happens when activities are deleted, either through the API or when cleaning rules apply.

Design consequences

If you want
Then

Fewer, richer UserPoints

Collect a strong shared identifier - an account ID or an email hash - as early in the journey as you can.

To avoid unwanted joins

Be careful with identifiers shared between people, such as a household device or a shared account.

Predictable analytics

Remember that merges rewrite history: counts of UserPoints move as merges happen.

To avoid hyper points

Watch identifier churn per registry, and question integrations that mint new identifiers frequently.

Verify

  • A test user logging in on two devices ends up as one UserPoint carrying both device points.

  • An anonymous visit creates a UserPoint carrying only a device identifier.

  • No ordinary user is flagged as a hyper point or in quarantine.

Last updated

Was this helpful?