> 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/collaboration/plan-and-integrate/understand-data-collaboration-concepts/matching-keys.md).

# Matching keys

The user identifiers you can use to match your dataset with your partner's, including clean room identifiers for identifiers stored differently on each side.

## What a matching key is

A **matching key** is a user identifier that can be used to match your dataset with your partner's. Supported **standard identifiers** today - platform-level identifiers that mean the same thing for every organisation, so they need no mapping:

* Email (plain text or hashed)
* Mobile Advertising ID (AAID & IDFA)
* Network ID (First-ID, ID5, UTIQ)
* TV Advertising ID (Tizen, IDFA, Roku, AAID, Fire TV)
* Cookie mediarithmics

{% hint style="info" %}
Agree with your partner on the hash method used for Email if you intend to use it as a matching key.
{% endhint %}

When you and your partner hold the same identifier but store it differently, match on a [clean room identifier](#clean-room-identifiers) instead.

How recent an online identifier must be to be matched is set by the **identifier freshness** of each matching - see [Analyze cross-partner behavior](https://docs.mediarithmics.io/collaboration/collaborate-with-a-partner/analyze-cross-partner-behavior.md#datasets-matching) - and, for auto-matching, by your [Clean Room Template](https://docs.mediarithmics.io/collaboration/prepare-your-environment/manage-your-clean-room-templates.md#what-a-clean-room-template-declares).

## Clean room identifiers

Two partners often hold the same identifier values, stored differently on each side: one keeps them as user accounts, the other as device IDs. A matching on either identifier compares two different identifier spaces and finds nothing, even though the values are identical.

A **clean room identifier** is an identifier space created for one Clean Room, with a name and an optional description. It exists only in that Clean Room. Each participating organisation **maps** it to the identifier that holds those values on its own side:

* a [**User Account Id**](https://docs.mediarithmics.io/setup-and-monitor/collect-and-manage-your-data/design-your-data-model-and-schema/understand-mediarithmics-standard-objects/user-account.md), in a given compartment, or
* a [**User Device Id**](https://docs.mediarithmics.io/setup-and-monitor/collect-and-manage-your-data/design-your-data-model-and-schema/understand-mediarithmics-standard-objects/user-device.md), in a given registry.

When you select the clean room identifier as the matching key, the platform resolves each side's mapping automatically, so neither partner needs to know how the other stores its data.

{% hint style="info" %}
**Worked through.** An internet service provider and a broadcaster hold the same set-top box IDs. A clean room identifier named **Box ID** is mapped to an account ID on the provider's side and to a device ID on the broadcaster's side. Selecting **Box ID** as the matching key connects both sides.
{% endhint %}

### Status

A clean room identifier is **incomplete** until every participating organisation has declared its mapping: it shows in the list of matching keys, but cannot be selected. Once every mapping is declared, it is **complete** and can be used as a matching key. Removing a mapping makes it incomplete again.

### Rules to know

* A clean room identifier connects the participating organisations of a Clean Room.
* An identifier - the user accounts of a given compartment, or the device IDs of a given registry - can be mapped by only one clean room identifier within a Clean Room. Mapping it to a second one is rejected.
* A mapping points to a User Account Id or a User Device Id.

### Set up a clean room identifier

{% stepper %}
{% step %}

#### Create the clean room identifier

The Clean Room's [Administrator](https://docs.mediarithmics.io/collaboration/plan-and-integrate/understand-data-collaboration-concepts/clean-rooms.md#clean-room-collaborators) goes to **Settings > Data Clean Room > Clean room identifiers**, creates a clean room identifier for the Clean Room with a name and an optional description, and declares its own mapping.
{% endstep %}

{% step %}

#### Declare the partner's mapping

An admin of the partner organisation opens the same clean room identifier, in **Settings > Data Clean Room > Clean room identifiers**, and declares the identifier to use on its side. The clean room identifier is then complete.
{% endstep %}
{% endstepper %}

## Where each kind of identifier appears

<table data-search="false"><thead><tr><th width="260">Where you pick a matching key</th><th>What you can select</th></tr></thead><tbody><tr><td>Creating a dataset from a file</td><td><strong>Standard identifier</strong>, and <strong>Private identifier</strong>: the identifiers of your own environment, as <strong>User Account Id</strong> per compartment and <strong>User Device Id</strong> per registry.</td></tr><tr><td>A Clean Room Template, for auto-matching</td><td><strong>Standard identifier</strong>. See the warning below.</td></tr><tr><td>Creating a matching</td><td><strong>Standard identifier</strong>, and <strong>Clean room identifier</strong>: the clean room identifiers of that Clean Room.</td></tr></tbody></table>

{% hint style="warning" %}
At the moment, clean room identifiers are not compatible with Clean Room Templates: a template cannot reference a private identifier as a matching key for auto-matching. This compatibility will be added in a future release.
{% endhint %}

Once a dataset matched on a private identifier is shared in a Clean Room, its listing shows the name of the clean room identifier that maps that private identifier, so both partners read the same name.

## 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>Datasets</strong></td><td>What a dataset is, its types and sources, and which combinations are available.</td><td><a href="https://docs.mediarithmics.io/collaboration/plan-and-integrate/understand-data-collaboration-concepts/datasets.md">Datasets</a></td></tr><tr><td><strong>Analyze cross-partner behavior</strong></td><td>Match a shared dataset with your partner's.</td><td><a href="https://docs.mediarithmics.io/collaboration/collaborate-with-a-partner/analyze-cross-partner-behavior.md">Analyze cross-partner behavior</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/collaboration/plan-and-integrate/understand-data-collaboration-concepts/matching-keys.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.
