| title | UID2 Endpoints - Summary |
|---|---|
| description | Summary of the endpoints available in the UID2 service. |
| hide_table_of_contents | false |
| sidebar_position | 1 |
| displayed_sidebar | docs |
import Link from '@docusaurus/Link';
All UID2 endpoints require a client secret for encrypting API requests (except POST /token/refresh requests) and decrypting responses. For details, and code examples in different programming languages, see Encrypting Requests and Decrypting Responses.
The following table shows the UID2 endpoints, with the audience for each. For details, click through to the applicable sections.
| Endpoint | Audience | Details |
|---|---|---|
| POST /token/generate | Publishers | UID2 Tokens |
| POST /token/validate | Publishers | UID2 Tokens |
| POST /token/refresh | Publishers | UID2 Tokens |
| POST /identity/map | Advertisers, data providers | Identity Map |
| POST /optout/status | Advertisers, data providers, DSPs, sharers | Opt-Out Status |
The following endpoints are for retrieving and managing UID2 tokens (identity tokens, advertising tokens), and are used mainly by publishers.
| Endpoint | Description | Request Encryption | Response Decryption |
|---|---|---|---|
| POST /token/generate | Requests a UID2 token generated from a user's DII (email address or phone number). If the DII is valid, and the user has not opted out of UID2, this operation returns a UID2 token and associated values. | Required | Required |
| POST /token/validate | Used for testing, to validate that an advertising token (UID2) matches the specified email address, phone number, or the respective hash. | Required | Required |
| POST /token/refresh | Generates a new token for a user for their refresh token from the POST /token/generate response. | N/A | Required |
The following endpoints are used by advertisers and third-party data providers. Publishers do not need to use these endpoints.
In the latest identity map integration, you only need to call one endpoint, POST /identity/map. The POST /identity/buckets endpoint is not part of the workflow.
:::important If you're using the earlier version, we recommend that you upgrade as soon as possible, to take advantage of improvements. :::
The latest identity map integration uses the following endpoint:
| Endpoint | Description | Request Encryption | Response Decryption |
|---|---|---|---|
| POST /identity/map | Maps raw UID2s, previous raw UID2s, and refresh timestamps for one or more email addresses, phone numbers, or their respective hashes. | Required | Required |
The following endpoints are part of the earlier identity map integration (version 2).
| Endpoint | Description | Request Encryption | Response Decryption |
|---|---|---|---|
| POST /identity/buckets | Monitors rotated salt buckets using their last updated timestamp. | Required | Required |
| POST /identity/map (v2) | Maps raw UID2s and salt bucket IDs for one or more email addresses, phone numbers, or their respective hashes. | Required | Required |
The following endpoint can be used by advertisers, third-party data providers, DSPs, and sharers. Publishers do not need to use this endpoint.
For details about the UID2 opt-out workflow and how users can opt out, see User Opt-Out.
| Endpoint | Description | Request Encryption | Response Decryption |
|---|---|---|---|
| POST /optout/status | Checks the opt-out status of UID2s. This endpoint takes a list of UID2s as input, and returns the UID2s that have opted out, as well as the time that the opt-out took place. | Required | Required |