> 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/resolve-identities.md).

# Resolve identities

Improve how many of your users are recognised as one person, and repair links that are wrong.

## Your goal

Increase the share of your data that lands on a single UserPoint per real person - by collecting the right identifiers at the right moment, and by declaring the links the platform cannot infer on its own.

## Expected outcome

Fewer UserPoints per real user, more complete histories, and no ordinary user flagged as a hyper point.

## What resolution the platform does by itself

**Automatic identity resolution** merges two UserPoints when it learns they represent the same person. It happens on its own, and it can only be triggered by two things:

* **UserActivity updates** - an activity arriving with more than one identifier, one of which is already known on another UserPoint.
* **User identifier association declarations** - you telling the platform explicitly that identifiers belong together.

The mechanics, and what a merge does to your data, are in [UserPoint & Identity graph](/setup-and-monitor/collect-and-manage-your-data/design-your-data-model-and-schema/user-identity/userpoint-and-identity-graph.md).

{% hint style="info" %}
The advice on this page applies whatever your [deployment mode](/setup-and-monitor/plan-and-integrate/choose-your-deployment-mode.md): sending more identifiers, earlier, and hashing them consistently improves resolution in all of them. Where your cloud data warehouse is the source of truth, the graph is computed there and a change to your identity configuration triggers a full recomputation over the whole history, which is worth planning rather than discovering. 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).
{% endhint %}

## What you can do to improve it

{% stepper %}
{% step %}

### Send every identifier you have, on every activity

Resolution only happens when identifiers meet. An activity that carries a device identifier *and* an account ID is what joins the anonymous history to the known customer; an activity that carries only one of them never will.

Send them together in the `$user_identifiers` list. See [User identifiers](/setup-and-monitor/collect-and-manage-your-data/design-your-data-model-and-schema/user-identity/user-identifiers.md).
{% endstep %}

{% step %}

### Collect a person-level identifier as early as you can

A device identifier only ever identifies a device. Recognition across devices requires an account ID or an email hash, so the earlier in the journey you capture one, the more history consolidates.
{% endstep %}

{% step %}

### Hash emails identically everywhere

A hash produced by a different function is a different identifier and will never match. Agree the function once per datamart, and apply it in every integration.
{% endstep %}

{% step %}

### Declare the links you already know

Your own systems often know that two identifiers belong to the same person - a CRM that stores both a hashed email and an account ID, for example. You can declare those associations in bulk, and each declaration creates or merges a UserPoint holding all the identifiers on the line.

Any combination of identifier types can be declared together: email hashes, user agents, and account IDs.

{% hint style="info" %}
Association declarations are only supported for datamarts using a UserPoint system version of `v201812` or later.
{% endhint %}

The import format and worked commands are in [Enrich users with identifiers](/setup-and-monitor/collect-and-manage-your-data/import-data-in-batch/enrich-users-with-identifiers.md).
{% endstep %}

{% step %}

### Add network IDs where your own identifiers run out

Network IDs recognise users in environments where your identifiers do not reach. Note the trade-off: a probabilistic ID increases reach but is **not allowed to merge** device points or UserPoints.

[Network IDs](/setup-and-monitor/collect-and-manage-your-data/design-your-data-model-and-schema/user-identity/network-ids.md)
{% endstep %}
{% endstepper %}

## What you cannot undo

{% hint style="warning" %}
A merge migrates all content and identifiers onto the surviving UserPoint and archives the other. There is no "unmerge" step in the model, so a declaration that wrongly associates two people permanently joins their histories.

Validate association files before importing them, especially when they are produced by a join in your own systems.
{% endhint %}

The same caution applies to shared identifiers: a household device, a shared account, or a shop tablet will consolidate several real people into one UserPoint if it is treated as a strong identifier.

## What to watch

| Signal                                                   | What it tells you                                                                                                                                                                                                    | Where                                                                                                                                                                     |
| -------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| UserPoint volume growing faster than your real user base | Identifiers are being minted rather than matched - a format problem, or a missing registry.                                                                                                                          | [Monitor collection volume](/setup-and-monitor/operate-and-monitor/monitor-collection-volume.md)                                                                          |
| Ordinary users flagged as **hyper points**               | Too many identifiers accumulating on one UserPoint: more than 10 per registry ID in 2 days, more than 4 account IDs or email hashes in 7 days, more than 8 merges in 14 days, or more than 100 identifiers in total. | [UserPoint & Identity graph](/setup-and-monitor/collect-and-manage-your-data/design-your-data-model-and-schema/user-identity/userpoint-and-identity-graph.md#hyper-point) |
| Users in **quarantine**                                  | More than 10,000 activities or 5,000 segments on one UserPoint - usually over-consolidation, or retention that is too long.                                                                                          | [UserPoint & Identity graph](/setup-and-monitor/collect-and-manage-your-data/design-your-data-model-and-schema/user-identity/userpoint-and-identity-graph.md#quarantine)  |
| A known test user split across UserPoints                | An identifier is not being sent where you assumed it was.                                                                                                                                                            | [Explore a user profile](/setup-and-monitor/operate-and-monitor/explore-a-user-profile.md)                                                                                |

## Verify

* A test user logging in on two devices consolidates into one UserPoint.
* Association declarations produce the number of merges you expected, not several times more.
* Segment metrics counting accounts and emails move in the direction you expect after an improvement.
* No ordinary user is flagged as a hyper point or quarantined.

## 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>Enrich users with identifiers</strong></td><td>The import that declares associations.</td><td><a href="/setup-and-monitor/collect-and-manage-your-data/import-data-in-batch/enrich-users-with-identifiers.md">Enrich users with identifiers</a></td></tr><tr><td><strong>UserPoint &#x26; Identity graph</strong></td><td>Merge rules, hyper points, and quarantine.</td><td><a href="/setup-and-monitor/collect-and-manage-your-data/design-your-data-model-and-schema/user-identity/userpoint-and-identity-graph.md">UserPoint &amp; Identity graph</a></td></tr><tr><td><strong>Delete user data</strong></td><td>Removing identifiers and UserPoints.</td><td><a href="/setup-and-monitor/collect-and-manage-your-data/clean-and-delete-data/delete-user-data.md">Delete user data</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/resolve-identities.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.