> 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/user-identifiers.md).

# User identifiers

The three types of user identifier, and how to send them.

## Your goal

Pick the identifiers you will send with every activity and import, and send them in the form the platform expects.

## Expected outcome

Each of your data sources carries at least one identifier the platform can resolve, and the identifiers are formatted consistently across all of them.

## The three types

| Type                                                                                                                                                 | What it identifies                                                                       | Requires                                                                                                      |
| ---------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------- |
| [**User Account**](/setup-and-monitor/collect-and-manage-your-data/design-your-data-model-and-schema/user-identity/user-identifiers/user-account.md) | A user registered in one of your systems - CRM, loyalty programme, authentication system | A [compartment](/setup-and-monitor/plan-and-integrate/set-up-the-environment/set-up-compartments.md)          |
| [**User Email**](/setup-and-monitor/collect-and-manage-your-data/design-your-data-model-and-schema/user-identity/user-identifiers/user-email.md)     | A user by their email address, normally hashed                                           | A consistent hash function                                                                                    |
| [**User Device**](/setup-and-monitor/collect-and-manage-your-data/design-your-data-model-and-schema/user-identity/user-identifiers/user-device.md)   | A device, through one or more technical identifiers                                      | A [device registry](/setup-and-monitor/plan-and-integrate/set-up-the-environment/set-up-device-registries.md) |

## How you send them

Identifiers travel in the `$user_identifiers` list of a [UserActivity](/setup-and-monitor/collect-and-manage-your-data/collect-data-in-real-time.md#the-useractivity-object). The list can hold **several identifiers of each type**.

{% tabs %}
{% tab title="User account" %}

| Field              | Type                | Description                                             |
| ------------------ | ------------------- | ------------------------------------------------------- |
| `$type`            | Constant string     | `USER_ACCOUNT`                                          |
| `$compartment_id`  | Integer             | The ID of the compartment associated with this activity |
| `$user_account_id` | String              | The user account ID of the user                         |
| `$expiration_ts`   | Timestamp, optional | The account's expiration timestamp                      |
| {% endtab %}       |                     |                                                         |

{% tab title="User email" %}

| Field            | Type                | Description                      |
| ---------------- | ------------------- | -------------------------------- |
| `$type`          | Constant string     | `USER_EMAIL`                     |
| `$hash`          | String              | The email hash                   |
| `$email`         | String, optional    | The raw email                    |
| `$expiration_ts` | Timestamp, optional | The email's expiration timestamp |
| {% endtab %}     |                     |                                  |

{% tab title="User agent" %}

| Field            | Type                | Description                                                                                                     |
| ---------------- | ------------------- | --------------------------------------------------------------------------------------------------------------- |
| `$type`          | Constant string     | `USER_AGENT`                                                                                                    |
| `$user_agent_id` | String              | The user agent ID. Currently supported agent type: vector ID, `vec:<vector_id>` - for example `vec:89090939434` |
| `$expiration_ts` | Timestamp, optional | The agent's expiration timestamp                                                                                |

The full set of identifier formats for devices - cookies, mobile IDs, CTV IDs, network IDs - is in [User Device](/setup-and-monitor/collect-and-manage-your-data/design-your-data-model-and-schema/user-identity/user-identifiers/user-device.md).
{% endtab %}
{% endtabs %}

{% hint style="warning" %}
For user identification, **either** use `$user_identifiers`, **or** use the legacy properties `$user_agent_id`, `$user_account_id` with `$compartment_id`, and `$email_hash`. Do not mix the two approaches.

`$user_identifiers` is the recommended form - the legacy properties are marked as such in the platform's own documentation of the activity object.
{% endhint %}

## What happens when an identifier arrives

* An activity or import carrying one of these properties is **automatically related to the correct UserPoint**.
* An activity using an identifier that does not already exist in the datamart **triggers the creation of a new UserPoint**.
* Identifiers that link two existing UserPoints cause a [merge](/setup-and-monitor/collect-and-manage-your-data/design-your-data-model-and-schema/user-identity/userpoint-and-identity-graph.md#userpoint-merges).

## Working with identifiers in bulk

You can **associate, dissociate, or delete** user identifiers in bulk using the batch import features:

* [Enrich users with identifiers](/setup-and-monitor/collect-and-manage-your-data/import-data-in-batch/enrich-users-with-identifiers.md) - declare that identifiers belong together.
* [Import identifiers](/setup-and-monitor/collect-and-manage-your-data/import-data-in-batch/import-identifiers.md) - send identifiers as documents.
* [Delete user data](/setup-and-monitor/collect-and-manage-your-data/clean-and-delete-data/delete-user-data.md) - remove identifiers or whole UserPoints.

## Verify

* Every source sends at least one identifier the platform can resolve.
* Account IDs are always accompanied by a compartment ID.
* Email hashes use the same function everywhere.
* Device identifiers reference a registry that exists.

## 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>UserPoint &#x26; Identity graph</strong></td><td>What the platform does with these identifiers.</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>Network IDs</strong></td><td>Third-party identifiers, device-based and user-based.</td><td><a href="/setup-and-monitor/collect-and-manage-your-data/design-your-data-model-and-schema/user-identity/network-ids.md">Network IDs</a></td></tr><tr><td><strong>Resolve identities</strong></td><td>Declare associations between identifiers.</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></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/user-identifiers.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.