Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
6 changes: 3 additions & 3 deletions docs/endpoints/post-identity-buckets.md
Original file line number Diff line number Diff line change
Expand Up @@ -31,7 +31,7 @@ You must encrypt all requests using your secret. For details, and code examples

### Path parameters

| Path Parameter | Data Type | Attribute | Description |
| Path parameter | Data type | Attribute | Description |
| :--- | :--- | :--- | :--- |
| `{environment}` | string | Required | Testing (integration) environment: `https://operator-integ.uidapi.com`<br/>Production environment: The best choice depends on where your users are based. For information about how to choose the best URL for your use case, and a full list of valid base URLs, see [Environments](../getting-started/gs-environments.md). |

Expand All @@ -45,7 +45,7 @@ The integration environment and the production environment require different <Li
You must include the following parameter as a key-value pair in the JSON body of a request when encrypting it.
:::

| Body Parameter | Data Type | Attribute | Description | Format |
| Body parameter | Data type | Attribute | Description | Format |
| :--- | :--- | :--- | :--- | :--- |
| `since_timestamp` | date-time or integer | Required | Specify the date and time to which to compare the last updated UTC timestamps of the buckets to be returned. | ISO 8601 format:<br/>`YYYY-MM-DDThh:mm:ss` |

Expand Down Expand Up @@ -106,7 +106,7 @@ The response body includes the properties shown in the following table.

The following table lists the `status` property values and their HTTP status code equivalents.

| Status | HTTP Status Code | Description |
| Status | HTTP status code | Description |
| :--- | :--- | :--- |
| `success` | 200 | The request was successful. The response will be encrypted. |
| `client_error` | 400 | The request had missing or invalid parameters. |
Expand Down
8 changes: 4 additions & 4 deletions docs/endpoints/post-identity-map-v2.md
Original file line number Diff line number Diff line change
Expand Up @@ -48,7 +48,7 @@ You must encrypt all requests using your secret. For details, and code examples

### Path parameters

| Path Parameter | Data Type | Attribute | Description |
| Path parameter | Data type | Attribute | Description |
| :--- | :--- | :--- | :--- |
| `{environment}` | string | Required | Testing (integration) environment: `https://operator-integ.uidapi.com`<br/>Production environment: The best choice depends on where your users are based. For information about how to choose the best URL for your use case, and a full list of valid base URLs, see [Environments](../getting-started/gs-environments.md). |

Expand All @@ -62,7 +62,7 @@ The integration environment and the production environment require different <Li
You must include only **one** of the following four conditional parameters as a key-value pair in the JSON body of the request when encrypting it.
:::

| Body Parameter | Data Type | Attribute | Description |
| Body parameter | Data type | Attribute | Description |
| :--- | :--- | :--- | :--- |
| `email` | string array | Conditionally Required | The list of email addresses to be mapped. |
| `email_hash` | string array | Conditionally Required | The list of [Base64-encoded SHA-256](../getting-started/gs-normalization-encoding.md#email-address-hash-encoding) hashes of [normalized](../getting-started/gs-normalization-encoding.md#email-address-normalization) email addresses to be mapped. |
Expand Down Expand Up @@ -192,7 +192,7 @@ If some identifiers have opted out from the UID2 ecosystem, the opted-out identi

The response body includes the properties shown in the following table.

| Property | Data Type | Description |
| Property | Data type | Description |
| :--- | :--- | :--- |
| `identifier` | string | The email address, phone number, or respective hash specified in the request body. |
| `advertising_id` | string | The corresponding advertising ID (raw UID2). |
Expand All @@ -202,7 +202,7 @@ The response body includes the properties shown in the following table.

The following table lists the `status` property values and their HTTP status code equivalents.

| Status | HTTP Status Code | Description |
| Status | HTTP status code | Description |
| :--- | :--- | :--- |
| `success` | 200 | The request was successful. The response will be encrypted. |
| `client_error` | 400 | The request had missing or invalid parameters.|
Expand Down
22 changes: 11 additions & 11 deletions docs/endpoints/post-identity-map.md
Original file line number Diff line number Diff line change
Expand Up @@ -48,7 +48,7 @@ You must encrypt all requests using your secret. For details, and code examples

### Path parameters

| Path Parameter | Data Type | Attribute | Description |
| Path parameter | Data type | Attribute | Description |
| :--- | :--- | :--- | :--- |
| `{environment}` | string | Required | Testing (integration) environment: `https://operator-integ.uidapi.com`<br/>Production environment: The best choice depends on where your users are based. For information about how to choose the best URL for your use case, and a full list of valid base URLs, see [Environments](../getting-started/gs-environments.md). |

Expand All @@ -62,7 +62,7 @@ The integration environment and the production environment require different <Li
Include one or more of the following four parameters as key-value pairs in the JSON body of the request when encrypting it.
:::

| Body Parameter | Data Type | Attribute | Description |
| Body parameter | Data type | Attribute | Description |
|:---------------|:----------------------------|:-----------------------| :--- |
| `email` | string array | Conditionally Required | The list of email addresses to be mapped. |
| `email_hash` | string array | Conditionally Required | The list of [Base64-encoded SHA-256](../getting-started/gs-normalization-encoding.md#email-address-hash-encoding) hashes of [normalized](../getting-started/gs-normalization-encoding.md#email-address-normalization) email addresses to be mapped. |
Expand Down Expand Up @@ -166,7 +166,7 @@ Response:

The response body includes one or more of the properties shown in the following table.

| Body Parameter | Data Type | Description |
| Body parameter | Data type | Description |
|:---------------|:----------------------------|:------------------------------------------------------------------------------------------------|
| `email` | array of mapped DII objects | The list of mapped DII objects corresponding to the list of emails in the request. |
| `email_hash` | array of mapped DII objects | The list of mapped DII objects corresponding to the list of email hashes in the request. |
Expand All @@ -176,7 +176,7 @@ The response body includes one or more of the properties shown in the following

For successfully mapped DII, the mapped object includes the properties shown in the following table.

| Property | Data Type | Description |
| Property | Data type | Description |
|:---------|:-----------|:--------------------------------------------------------------------------------------------------------------------------------------|
| `u` | string | The raw UID2 corresponding to the email or phone number provided in the request. |
| `p` | string | One of the following:<ul><li>If the current raw UID2 was rotated in the last 90 days: the previous raw UID2.</li><li>Otherwise: `null`.</li></ul> |
Expand All @@ -188,15 +188,15 @@ The raw UID2 does not change before the refresh timestamp. After the refresh tim

For unsuccessfully mapped input values, the mapped object includes the properties shown in the following table.

| Property | Data Type | Description |
| Property | Data type | Description |
|:---------|:----------|:-----------------------------------------------------------------------------------------------------------------|
| `e` | string | The reason for being unable to map the DII to a raw UID2. One of two possible values:<ul><li>`optout`</li><li>`invalid identifier`</li></ul> |

### Response status codes

The following table lists the `status` property values and their HTTP status code equivalents.

| Status | HTTP Status Code | Description |
| Status | HTTP status code | Description |
| :--- | :--- | :--- |
| `success` | 200 | The request was successful. The response will be encrypted. |
| `client_error` | 400 | The request had missing or invalid parameters. |
Expand Down Expand Up @@ -226,12 +226,12 @@ The following sections provide general information and guidance for migrating to

The following table shows key differences between the versions.

| Feature | v2 Implementation | v3 Implementation |
| Feature | v2 implementation | v3 implementation |
|:-------------------------------|:--------------------------------------------|:-------------------------------------------|
| Endpoints Required | `/v2/identity/map` + `/v2/identity/buckets` | `/v3/identity/map` only |
| Identity Types per Request | Single identity type only | Multiple identity types |
| Refresh Management | Monitor salt bucket rotations via `/identity/buckets` endpoint | Re-map when past `refresh_from` timestamps |
| Previous UID2 Access | Not available | Available for 90 days |
| Endpoints required | `/v2/identity/map` + `/v2/identity/buckets` | `/v3/identity/map` only |
| Identity types per request | Single identity type only | Multiple identity types |
| Refresh management | Monitor salt bucket rotations via `/identity/buckets` endpoint | Re-map when past `refresh_from` timestamps |
| Previous UID2 access | Not available | Available for 90 days |

### Required changes

Expand Down
6 changes: 3 additions & 3 deletions docs/endpoints/post-optout-status.md
Original file line number Diff line number Diff line change
Expand Up @@ -38,7 +38,7 @@ You must encrypt all requests using your secret. For details, and code examples

### Path parameters

| Path Parameter | Data Type | Attribute | Description |
| Path parameter | Data type | Attribute | Description |
| :--- | :--- | :--- | :--- |
| `{environment}` | string | Required | Testing (integration) environment: `https://operator-integ.uidapi.com`<br/>Production environment: The best choice depends on where your users are based. For information about how to choose the best URL for your use case, and a full list of valid base URLs, see [Environments](../getting-started/gs-environments.md). |

Expand All @@ -50,7 +50,7 @@ The integration environment and the production environment require different <Li

There is a single body parameter.

| Body Parameter | Data Type | Attribute | Description |
| Body parameter | Data type | Attribute | Description |
| :--- | :--- | :--- | :--- |
| `advertising_ids` | string array | Required | The list of raw UID2s for which you want to check the opt-out status.<br/>Include a maximum of 5,000 entries in one API call. |

Expand Down Expand Up @@ -115,7 +115,7 @@ The response body includes the following properties.

The following table lists the status property values and their HTTP status code equivalents.

| Status | HTTP Status Code | Description |
| Status | HTTP status code | Description |
| :--- | :--- | :--- |
| `success` | 200 | The request was successful. The response will be encrypted. |
| `client_error` | 400 | The request had missing or invalid parameters. |
Expand Down
10 changes: 5 additions & 5 deletions docs/endpoints/post-token-generate.md
Original file line number Diff line number Diff line change
Expand Up @@ -34,7 +34,7 @@ Here's what you need to know about sending requests to this endpoint:

### Path parameters

| Path Parameter | Data Type | Attribute | Description |
| Path parameter | Data type | Attribute | Description |
| :--- | :--- | :--- | :--- |
| `{environment}` | string | Required | Testing (integration) environment: `https://operator-integ.uidapi.com`<br/>Production environment: The best choice depends on where your users are based. For information about how to choose the best URL for your use case, and a full list of valid base URLs, see [Environments](../getting-started/gs-environments.md).<br/>Notes:<ul><li>The `integ` environment and the `prod` environment require different <Link href="../ref-info/glossary-uid#gl-api-key">API keys</Link>.</li><li>Token expiration time is subject to change, but is always significantly shorter in the `integ` environment than it is in the `prod` environment.</li></ul> |

Expand All @@ -44,7 +44,7 @@ Here's what you need to know about sending requests to this endpoint:
You must include only **one** of the following four conditional parameters as key-value pairs in the JSON body of the request when encrypting it.
:::

| Body Parameter | Data Type | Attribute | Description |
| Body parameter | Data type | Attribute | Description |
| :--- | :--- | :--- | :--- |
| `email` | string | Conditionally Required | The email address for which to generate tokens. |
| `email_hash` | string | Conditionally Required | The [Base64-encoded SHA-256](../getting-started/gs-normalization-encoding.md#email-address-hash-encoding) hash of a [normalized](../getting-started/gs-normalization-encoding.md#email-address-normalization) email address. |
Expand Down Expand Up @@ -118,7 +118,7 @@ Here is an example response when the user has opted out.

The response body includes the properties shown in the following table.

| Property | Data Type | Description |
| Property | Data type | Description |
| :--- | :--- | :--- |
| `advertising_token` | string | An encrypted advertising (UID2) token for the user. |
| `refresh_token` | string | An encrypted token that can be exchanged with the UID2 Service for the latest set of identity tokens. |
Expand All @@ -131,7 +131,7 @@ The response body includes the properties shown in the following table.

The following table lists the `status` property values and their HTTP status code equivalents.

| Status | HTTP Status Code | Description |
| Status | HTTP status code | Description |
| :--- | :--- | :--- |
| `success` | 200 | The request was successful. The response will be encrypted. |
| `optout` | 200 | The request was successful. Could not generate token because the user has opted out. |
Expand All @@ -142,7 +142,7 @@ If the `status` value is anything other than `success`, the `message` field prov

## Test identities

| Type | Identity | Purpose | Next Endpoint |
| Type | Identity | Purpose | Next endpoint |
|:------|:-----------------------------|:-------------------------------------------------------------------------------------------------------------------------------------------|:----------------------------------------------------|
| Email | `validate@example.com` | Test that the `advertising_token` you've cached matches the `advertising_token` for the specified email address. | [POST&nbsp;/token/validate](post-token-validate.md) |
| Email | `optout@example.com` | Using this email for the request always generates an `optout` response. | [POST&nbsp;/token/generate](post-token-generate.md) |
Expand Down
6 changes: 3 additions & 3 deletions docs/endpoints/post-token-refresh.md
Original file line number Diff line number Diff line change
Expand Up @@ -35,7 +35,7 @@ Here's what you need to know about this endpoint:

### Path parameters

| Path Parameter | Data Type | Attribute | Description |
| Path parameter | Data type | Attribute | Description |
| :--- | :--- | :--- | :--- |
| `{environment}` | string | Required | Testing (integration) environment: `https://operator-integ.uidapi.com`<br/>Production environment: The best choice depends on where your users are based. For information about how to choose the best URL for your use case, and a full list of valid base URLs, see [Environments](../getting-started/gs-environments.md).<br/>Notes:<ul><li>The `integ` environment and the `prod` environment require different <Link href="../ref-info/glossary-uid#gl-api-key">API keys</Link>.</li><li>Token expiration time is subject to change, but is always significantly shorter in the `integ` environment than it is in the `prod` environment.</li></ul> |

Expand Down Expand Up @@ -95,7 +95,7 @@ An error response might look like the following:

The response body includes the properties shown in the following table.

| Property | Data Type | Description |
| Property | Data type | Description |
| :--- | :--- | :--- |
| `advertising_token` | string | The <Link href="../ref-info/glossary-uid#gl-uid2-token">UID2 token</Link> (also known as advertising token) for the user. |
| `refresh_token` | string | An encrypted token that can be exchanged with the UID2 Service for the latest set of identity tokens. |
Expand All @@ -108,7 +108,7 @@ The response body includes the properties shown in the following table.

The following table lists the `status` property values and their HTTP status code equivalents.

| Status | HTTP Status Code | Description |
| Status | HTTP status code | Description |
| :--- | :--- | :--- |
| `success` | 200 | The request was successful and a new UID2 token, with associated values, is returned in the response. The response is encrypted. |
| `optout` | 200 | The user opted out. This status is returned only for authorized requests. The response is encrypted. |
Expand Down
8 changes: 4 additions & 4 deletions docs/endpoints/post-token-validate.md
Original file line number Diff line number Diff line change
Expand Up @@ -29,7 +29,7 @@ You must encrypt all requests using your secret key. For details, and code examp

### Path parameters

| Path Parameter | Data Type | Attribute | Description |
| Path parameter | Data type | Attribute | Description |
| :--- | :--- | :--- | :--- |
| `{environment}` | string | Required | Testing (integration) environment: `https://operator-integ.uidapi.com`<br/>Production environment: The best choice depends on where your users are based. For information about how to choose the best URL for your use case, and a full list of valid base URLs, see [Environments](../getting-started/gs-environments.md). |

Expand All @@ -44,7 +44,7 @@ Here are some key points about using this endpoint:
- Include only one of the following four valid options, as listed in the Body Parameter table: `email`, `email_hash`, `phone`, or `phone_hash`.
- Include the required body parameters as key-value pairs in the JSON body of the request when encrypting it.

| Body Parameter | Data Type | Attribute | Description |
| Body parameter | Data type | Attribute | Description |
| :--- | :--- | :--- | :--- |
| `token` | string | Required | The advertising token returned by the [POST&nbsp;/token/generate](post-token-generate.md) response.<br/>You can only validate an advertising token that has been generated with your own credentials.
| `email` | string | Conditionally Required | The email address for token validation. You can use any valid email value, normalized or not. |
Expand Down Expand Up @@ -112,15 +112,15 @@ A successful decrypted response returns a boolean value that indicates the valid

The following table provides information about the response body.

| Property | Data Type | Description |
| Property | Data type | Description |
| :--- | :--- | :--- |
| `body` | boolean | A value of `true` indicates that the email address, phone number, or the respective hash specified in the request is the same as the one used to generate the advertising token.<br/>A value of `false` indicates that the email address, phone number, or the respective hash specified in the request is not the same as the one used to generated the advertising token. |

### Response status codes

The following table lists the `status` property values and their HTTP status code equivalents.

| Status | HTTP Status Code | Description |
| Status | HTTP status code | Description |
| :--- | :--- | :--- |
| `success` | 200 | The request was successful. The response will be encrypted. |
| `client_error` | 400 | The request had missing or invalid parameters. |
Expand Down
Loading