> For the complete documentation index, see [llms.txt](https://docs.mediarithmics.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.mediarithmics.io/setup-and-monitor/collect-and-manage-your-data/design-your-data-model-and-schema/user-identity/userpoint-and-identity-graph.md).

# 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](/setup-and-monitor/understand-mediarithmics/how-mediarithmics-works.md#how-your-data-is-modelled-the-userpoint), and the user can be **identified or anonymous**.

```mermaid
flowchart TD
    UP(("UserPoint"))
    A1["UserAccount<br/>compartment 1"]
    A2["UserAccount<br/>compartment 2"]
    EM["UserEmail<br/>hash"]
    D1["UserDevicePoint<br/>PC / Chrome"]
    D2["UserDevicePoint<br/>Android tablet"]
    T1["UserDeviceTechnicalId<br/>first-party cookie"]
    T2["UserDeviceTechnicalId<br/>network ID"]
    T3["UserDeviceTechnicalId<br/>mobile advertising ID"]
    UP --- A1
    UP --- A2
    UP --- EM
    UP --- D1
    UP --- D2
    D1 --- T1
    D1 --- T2
    D2 --- T3
```

Two 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 [User Device](/setup-and-monitor/collect-and-manage-your-data/design-your-data-model-and-schema/user-identity/user-identifiers/user-device.md).

## Where the graph is computed

The graph described here is the same whatever the datamart's [deployment mode](/setup-and-monitor/plan-and-integrate/choose-your-deployment-mode.md). What changes is where it is computed and how the underlying data is stored.

* When the datamart holds its own data, identifiers are reconciled as data is written, and the UserPoint is resolved at that moment.
* When your cloud data warehouse is the source of truth, activities and profiles are stored with the identifiers they arrived with and are not enriched with a UserPoint reference. Only the graph is computed, on the warehouse, which is what allows it to be rebuilt from the original history. See [Run your computation in the warehouse](/setup-and-monitor/collect-and-manage-your-data/sync-with-your-data-warehouse/run-your-computation-in-the-warehouse.md).

## 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](/setup-and-monitor/collect-and-manage-your-data/design-your-data-model-and-schema/user-identity/resolve-identities.md).

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.

```mermaid
sequenceDiagram
    participant F as UserPoint A<br/>(Firefox cookie)
    participant P as Platform
    participant S as UserPoint B<br/>(Safari cookie)
    F->>P: Activity, anonymous
    S->>P: Activity, anonymous
    S->>P: Activity with UserAccount ID
    F->>P: Activity with the same UserAccount ID
    P->>P: Same account on two UserPoints
    P->>F: Migrate content and identifiers to the older UserPoint
    P->>S: Archive
```

{% hint style="warning" %}
For identifiers considered **probabilistic** - those that can produce false-positive matches between users - the merge of device points and UserPoints is **not allowed**, to avoid inconsistencies in your ID graph. Contact your account manager about a specific identifier.
{% endhint %}

## When a UserPoint accumulates too much

Two 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.

## Related pages

<table data-view="cards" data-search="false"><thead><tr><th></th><th></th><th data-hidden data-card-target data-type="content-ref"></th></tr></thead><tbody><tr><td><strong>User identifiers</strong></td><td>The three identifier types in detail.</td><td><a href="/setup-and-monitor/collect-and-manage-your-data/design-your-data-model-and-schema/user-identity/user-identifiers.md">User identifiers</a></td></tr><tr><td><strong>Resolve identities</strong></td><td>Declaring associations, and repairing links.</td><td><a href="/setup-and-monitor/collect-and-manage-your-data/design-your-data-model-and-schema/user-identity/resolve-identities.md">Resolve identities</a></td></tr><tr><td><strong>Data planning and quality</strong></td><td>The checks that catch identity problems early.</td><td><a href="/setup-and-monitor/collect-and-manage-your-data/design-your-data-model-and-schema/data-planning-and-quality.md">Data planning and quality</a></td></tr></tbody></table>


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.mediarithmics.io/setup-and-monitor/collect-and-manage-your-data/design-your-data-model-and-schema/user-identity/userpoint-and-identity-graph.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.