Merge branch 'main' into staging-phase-2-identity-map-v3

Author: aulme

docs/endpoints/post-identity-buckets.md

@@ -15,9 +15,9 @@ Monitors rotated <Link href="../ref-info/glossary-uid#gl-salt-bucket">salt bucke
 Used by: This endpoint is used mainly by advertisers and data providers. For details, see [Advertiser/Data Provider Integration Overview](../guides/integration-advertiser-dataprovider-overview.md).
 
 :::important
-If you're using the latest version of `POST /v3/identity/map`, v3, you don't need to use `POST /identity/buckets` at all. You only need to use it if you're using the earlier version, `POST /v2/identity/map`.
+If you're using the latest version (v3) of `POST /v3/identity/map`, you don't need to use `POST /identity/buckets` at all. You only need to use it if you're using the earlier version (v2) of `POST /v2/identity/map`.
 
-If you're using the V2 version, we recommend that you upgrade as soon as possible, to take advantage of improvements. For migration guidance, see [Migration from V2 Identity Map](post-identity-map.md#migration-from-v2-identity-map).
+If you're using the v2 version, we recommend that you upgrade as soon as possible, to take advantage of improvements. For migration guidance, see [Migration from v2 Identity Map](post-identity-map.md#migration-from-v2-identity-map).
 :::
 
 ## Request Format

docs/endpoints/post-identity-map-v2.md

@@ -20,7 +20,7 @@ For details about the UID2 opt-out workflow and how users can opt out, see [User
 This documentation is for version 2 of this endpoint, which is not the latest version. For the latest version, v3, see [POST /identity/map](post-identity-map.md).
 
 :::note
-If you're using the V2 version, we recommend that you upgrade as soon as possible, to take advantage of improvements. For migration guidance, see [Migration from V2 Identity Map](post-identity-map.md#migration-from-v2-identity-map).
+If you're using the v2 version, we recommend that you upgrade as soon as possible, to take advantage of improvements. For migration guidance, see [Migration from v2 Identity Map](post-identity-map.md#migration-from-v2-identity-map).
 :::
 
 ## Batch Size and Request Parallelization Requirements

docs/endpoints/post-identity-map.md

@@ -174,7 +174,7 @@ For successfully mapped DII, the mapped object includes the properties shown in
 | 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 has been rotated in the last 90 days: the previous value.</li><li>If the current raw UID2 is older than 90 days: `Null`.</li></ul> |
+| `p`      | string     | One of the following:<ul><li>If the current raw UID2 has been rotated in the last 90 days: the previous value.</li><li>If the current raw UID2 is older than 90 days: `null`.</li></ul> |
 | `r`      | number     | The Unix timestamp (in milliseconds) that indicates when the raw UID2 might be refreshed. The raw UID2 is guaranteed to be valid until this timestamp. |
 
 For unsuccessfully mapped input values, the mapped object includes the properties shown in the following table.
@@ -195,26 +195,26 @@ The following table lists the `status` property values and their HTTP status cod
 
 If the `status` value is anything other than `success`, the `message` field provides additional information about the issue.
 
-## Migration from V2 Identity Map
+## Migration from v2 Identity Map
 
 The following sections provide general information and guidance for migrating to version 3 from earlier versions, including:
 
 - [Version 3 Improvements](#version-3-improvements)
-- [Key Differences Between V2 and V3](#key-differences-between-v2-and-v3)
+- [Key Differences Between v2 and v3](#key-differences-between-v2-and-v3)
 - [Required Changes](#required-changes)
 - [Additional Resources](#additional-resources)
 
 ### Version 3 Improvements
 
-The V3 Identity Map API provides the following improvements over V2:
+The v3 Identity Map API provides the following improvements over v2:
 
 - **Simplified Refresh Management**: You can monitor for UID2s reaching `refresh_from` timestamps instead of polling <Link href="../ref-info/glossary-uid#gl-salt-bucket-id">salt buckets</Link> for rotation.
 - **Previous UID2 Access**: You have access to previous raw UID2s for 90 days after rotation for campaign measurement.
 - **Single Endpoint**: You use only one endpoint, `/v3/identity/map`, instead of both `/v2/identity/map` and `/v2/identity/buckets`.
 - **Multiple Identity Types in One Request**: You can process both emails and phone numbers in a single request.
 - **Improved Performance**: The updated version uses significantly less bandwidth to process the same amount of DII.
 
-### Key Differences Between V2 and V3
+### Key Differences Between v2 and v3
 
 The following table shows key differences between the versions.
 
@@ -238,20 +238,20 @@ To upgrade from an earlier version to version 3, follow these steps:
 Update any reference to the endpoint URL so that it references the /v3/ implementation, as shown in the following example.
 
 ```python
-# Before (V2)
+# Before (v2)
 url = '/v2/identity/map'
 
-# After (V3) 
+# After (v3) 
 url = '/v3/identity/map'
 ```
 
-#### 2. Update V3 Response Parsing Logic
+#### 2. Update v3 Response Parsing Logic
 
 Update the logic for parsing the response, as shown in the following example.
 
 V2 Response Parsing:
 ```python
-# V2: Process mapped/unmapped objects with identifier lookup
+# v2: Process mapped/unmapped objects with identifier lookup
 for item in response['body']['mapped']:
     raw_uid = item['advertising_id']
     bucket_id = item['bucket_id']
@@ -262,7 +262,7 @@ for item in response['body']['mapped']:
 
 V3 Response Parsing:
 ```python
-# V3: Process array-indexed responses
+# v3: Process array-indexed responses
 for index, item in enumerate(response['body']['email']):
     original_email = request_emails[index]  # Use array index to correlate
     if 'u' in item:

docs/endpoints/summary-endpoints.md

@@ -26,7 +26,7 @@ The following endpoints are for retrieving and managing UID2 tokens (identity to
 
 The following endpoints are used by advertisers and third-party data providers. Publishers do not need to use these endpoints.
 
-### Latest Identity Map Endpoint (V3)
+### Latest Identity Map Endpoint (v3)
 
 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.
 
@@ -40,7 +40,7 @@ The latest identity map integration uses the following endpoint:
 | :--- | :--- | :--- | :--- |
 | [POST /identity/map](post-identity-map.md) | Maps raw UID2s, previous raw UID2s, and refresh timestamps for one or more email addresses, phone numbers, or their respective hashes.  | Required | Required |
 
-### Earlier Identity Map Endpoints (V2)
+### Earlier Identity Map Endpoints (v2)
 
 The following endpoints are part of the earlier identity map integration (version 2).  
 

docs/getting-started/gs-faqs.md

@@ -187,7 +187,7 @@ To determine whether to refresh a raw UID2:
 2. If the current time is greater than or equal to the refresh timestamp, regenerate the raw UID2 by calling the identity map endpoint again with the same <Link href="../ref-info/glossary-uid#gl-dii">DII</Link>.
 
 :::note
-We recommend checking for refresh opportunities daily. It is guaranteed that the raw UID2 won't refresh before the indicated timestamp. At some point after that time, the raw UID2 is refreshed.
+We recommend checking for refresh opportunities daily. It is guaranteed that the raw UID2 won't refresh before the indicated timestamp. At some point on or after that time, the raw UID2 is refreshed.
 :::
 
 #### How often should raw UID2s be refreshed for incremental updates?
@@ -196,7 +196,7 @@ The recommended cadence for updating audiences is daily.
 
 A raw UID2 for a specific user changes roughly once per year. The latest version of the [POST&nbsp;/identity/map](../endpoints/post-identity-map.md) endpoint provides refresh timestamps that indicate a point after which each raw UID2 might refresh. We recommend checking these timestamps daily to ensure your raw UID2s remain current and valid for audience targeting.
 
-For  implementations that reference earlier versions of this endpoint (see [POST&nbsp;/identity/map v2](../endpoints/post-identity-map-v2.md)):
+For implementations that reference earlier versions of this endpoint (see [POST&nbsp;/identity/map v2](../endpoints/post-identity-map-v2.md)):
 
 Even though each <Link href="../ref-info/glossary-uid#gl-salt-bucket">salt bucket</Link> is updated roughly once a year, individual bucket updates are spread over the year. This means that about 1/365th of all buckets are rotated daily. If fidelity is critical, consider calling the [POST&nbsp;/identity/buckets](../endpoints/post-identity-buckets.md) endpoint more frequently; for example, hourly.
 

docs/getting-started/gs-opt-out.md

@@ -20,7 +20,7 @@ Within the UID2 ecosystem, there are two types of opt out:
 
 Because each participant has their own opt-out workflow, participants are mandated to respect a user's opted-out status and therefore not create a UID2 for any user who opted out from the participant.
 
-For example, if a user opts out of a publisher's site, but has not opted out of UID2, the publisher should not generate a UID2 token for that user.  
+For example, if a user opts out of a publisher's site, but has not opted out of UID2, the publisher should not generate a UID2 token for that user.
 
 Consumers can always opt out of UID2 being used to show them personalized ads, in the [Transparency and Control Portal](https://www.transparentadvertising.com/). Choose email address or phone number, enter the data, and follow the prompts.
 
@@ -46,12 +46,12 @@ The following steps provide a high-level outline of the opt-out workflow intende
 2. The Transparency and Control Portal sends the opt-out request to the UID2 <Link href="../ref-info/glossary-uid#gl-operator-service">Operator Service</Link>.
 3. If the user has opted out, the UID2 Operator Service distributes the opt-out information to UID2 participants, as shown in the following table.
 
-   | Participant | Distribution Method                                                                                                                                                                                                                                                                                                                                  |
-   | :--- |:-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| 
-   | Publishers | A publisher calling  [POST&nbsp;/token/generate](../endpoints/post-token-generate.md) with the required `optout_check` parameter set to `1`, or [POST&nbsp;/token/refresh](../endpoints/post-token-refresh.md), receives the opt-out response instead of the UID2 token.                                                                             |
+   | Participant | Distribution Method |
+   | :--- | :--- | 
+   | Publishers | A publisher calling [POST&nbsp;/token/generate](../endpoints/post-token-generate.md) with the required `optout_check` parameter set to `1`, or [POST&nbsp;/token/refresh](../endpoints/post-token-refresh.md), receives the opt-out response instead of the UID2 token. |
    | DSPs | The UID2 Operator Service distributes information on all opted-out users to DSPs via a webhook provided for the purpose. For details, see [Honor User Opt-Outs](../guides/dsp-guide#honor-user-opt-outs).<br/>DSPs can also check the opt-out status of raw UID2s using the [POST&nbsp;/optout/status](../endpoints/post-optout-status.md) endpoint. |
-   | Advertisers and data providers | The UID2 Operator Service distributes opt-out information to advertisers and data providers via the [POST&nbsp;/identity/map](../endpoints/post-identity-map.md) endpoint. Another option is to check the opt-out status of raw UID2s using the [POST&nbsp;/optout/status](../endpoints/post-optout-status.md) endpoint.                          |
-   | Sharers | UID2 sharers can check the opt-out status of raw UID2s using the [POST&nbsp;/optout/status](../endpoints/post-optout-status.md) endpoint.                                                                                                                                                                                                            |
+   | Advertisers and data providers | The UID2 Operator Service distributes opt-out information to advertisers and data providers via the [POST&nbsp;/identity/map](../endpoints/post-identity-map.md) endpoint. Another option is to check the opt-out status of raw UID2s using the [POST&nbsp;/optout/status](../endpoints/post-optout-status.md) endpoint. |
+   | Sharers | UID2 sharers can check the opt-out status of raw UID2s using the [POST&nbsp;/optout/status](../endpoints/post-optout-status.md) endpoint. |
 
 This workflow allows users to opt out of personalized advertising based on their UID2 through the Transparency and Control Portal.
 

docs/getting-started/gs-permissions.md

@@ -22,9 +22,9 @@ A participant can have one or several sets of API credentials with associated pe
 
 The following table lists the key permissions, the types of participants that commonly use them, and a summary of the key associated activities.
 
-| Name | Participant Type | Permissions                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
-| :--- | :--- |:---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
+| Name | Participant Type | Permissions |
+| :--- | :--- | :--- |
 | Generator | Publishers | Permission to call the [POST&nbsp;/token/generate](../endpoints/post-token-generate.md), [POST&nbsp;/token/validate](../endpoints/post-token-validate.md), and [POST&nbsp;/token/refresh](../endpoints/post-token-refresh.md) endpoints, to generate UID2 tokens from <Link href="../ref-info/glossary-uid#gl-dii">DII</Link> and to refresh them, using one of these integration methods:<ul><li>A Prebid integration</li><li>The SDK for JavaScript</li><li>An integration that directly calls the applicable API endpoints for retrieving and managing UID2 tokens.</li></ul> |
-| Bidder | DSPs | Permission to decrypt UID2 tokens coming in from the <Link href="../ref-info/glossary-uid#gl-bidstream">bidstream</Link> from publishers into raw UID2s for bidding purposes.                                                                                                                                                                                                                                                                                                                                                                                                    |
-| Sharer | Any participant type that takes part in UID2 sharing. For details, see [UID2 Sharing: Overview](../sharing/sharing-overview.md). | Permission to do both of the following:<ul><li>Encrypt raw UID2s into UID2 tokens for sharing with another authorized sharing participant, using a UID2 SDK or Snowflake</li><li>Decrypt UID2 tokens received from another authorized sharing participant into raw UID2s.</li></ul>                                                                                                                                                                                                                                                                                              |
-| Mapper | Advertisers<br/>Data Providers | Permission to call the following endpoints  to map multiple email addresses, phone numbers, or their respective hashes to their raw UID2s, previous raw UID2s, and refresh timestamps:<ul><li>[POST&nbsp;/identity/map](../endpoints/post-identity-map.md) (latest version)</li><li>The earlier (version 2) identity mapping endpoints: [POST&nbsp;/identity/map (v2)](../endpoints/post-identity-map.md) and [POST&nbsp;/identity/buckets](../endpoints/post-identity-buckets.md).</li></ul>                                                                              |
+| Bidder | DSPs | Permission to decrypt UID2 tokens coming in from the <Link href="../ref-info/glossary-uid#gl-bidstream">bidstream</Link> from publishers into raw UID2s for bidding purposes. |
+| Sharer | Any participant type that takes part in UID2 sharing. For details, see [UID2 Sharing: Overview](../sharing/sharing-overview.md). | Permission to do both of the following:<ul><li>Encrypt raw UID2s into UID2 tokens for sharing with another authorized sharing participant, using a UID2 SDK or Snowflake</li><li>Decrypt UID2 tokens received from another authorized sharing participant into raw UID2s.</li></ul> |
+| Mapper | Advertisers<br/>Data Providers | Permission to call the following endpoints to map multiple email addresses, phone numbers, or their respective hashes to their raw UID2s, previous raw UID2s, and refresh timestamps:<ul><li>[POST&nbsp;/identity/map](../endpoints/post-identity-map.md) (latest version)</li><li>The earlier v2 identity mapping endpoints: [POST&nbsp;/identity/map (v2)](../endpoints/post-identity-map.md) and [POST&nbsp;/identity/buckets](../endpoints/post-identity-buckets.md).</li></ul> |