updates to Adv/DP integrate to endpoints doc

Author: genwhittTTD

docs/getting-started/gs-faqs.md

@@ -170,7 +170,7 @@ We do not make any promises about when the rotation takes place. To stay as up-t
 
 #### Do refreshed emails get assigned to the same bucket with which they were previously associated?
 
-Not necessarily. After you remap emails associated with a particular bucket ID, the emails might be assigned to a different bucket ID. To check the bucket ID, [call the mapping function](../guides/integration-advertiser-dataprovider-overview.md#1-retrieve-a-raw-uid2-for-dii) and save the returned UID2 and bucket ID again.
+Not necessarily. After you remap emails associated with a particular bucket ID, the emails might be assigned to a different bucket ID. To check the bucket ID, [call the mapping function](../guides/integration-advertiser-dataprovider-overview.md#retrieve-a-raw-uid2-for-dii) and save the returned UID2 and bucket ID again.
 
 :::info
 When mapping and remapping emails, do not make any assumptions about the number of buckets, their rotation dates, or the specific bucket that an email gets assigned to.
@@ -208,7 +208,7 @@ In general yes, the process of generating a raw UID2 from DII is the same, and r
 
 However, there is a variable factor, which is the <Link href="../ref-info/glossary-uid#gl-salt">salt</Link> value that's used in generating the raw UID2. The salt values are rotated roughly once per year (for details, see [How often should UID2s be refreshed for incremental updates?](#how-often-should-uid2s-be-refreshed-for-incremental-updates)). If the salt value changes between one request and another, those two requests result in two different raw UID2, even when the DII is the same.
 
-For more information, see [Monitor for salt bucket rotations related to your stored raw UID2s](../guides/integration-advertiser-dataprovider-overview.md#3-monitor-for-salt-bucket-rotations-related-to-your-stored-raw-uid2s) in the *Advertiser/Data Provider Integration Guide*.
+For more information, see [Monitor for salt bucket rotations related to your stored raw UID2s](../guides/integration-advertiser-dataprovider-overview.mdmonitor-for-salt-bucket-rotations-related-to-your-stored-raw-uid2s) in the *Advertiser/Data Provider Integration Guide*.
 
 #### If two operators process the same DII, are the results the same?
 

docs/guides/integration-advertiser-dataprovider-endpoints.md

@@ -1,5 +1,5 @@
 ---
-title: Advertiser/Data Provider Integration Directly to HTTP Endpoints
+title: Advertiser/Data Provider Integration to HTTP Endpoints
 sidebar_label: HTTP Endpoints
 description: Integration for organizations that collect user data and push it to other participants, coding to HTTP endpoints rather than an SDK or Snowflake.
 hide_table_of_contents: false
@@ -9,53 +9,69 @@ displayed_sidebar: sidebarAdvertisers
 
 import Link from '@docusaurus/Link';
 
-# Advertiser/Data Provider Integration Directly to HTTP Endpoints
+# Advertiser/Data Provider Integration to HTTP Endpoints
 
 This guide covers integration steps for advertisers and data providers to integrate with UID2 by writing code to call UID2 HTTP endpoints, rather than using another implementation options such as an SDK, Snowflake, or AWS Entity Resolution.
 
 :::tip
 For a summary of all integration options and steps for advertisers and data providers, see [Advertiser/Data Provider Integration Overview](integration-advertiser-dataprovider-overview.md).
 :::
 
-### High-Level Steps
+## Integration Diagram
+
+The following diagram outlines the steps that data collectors must complete to map DII to raw UID2s for audience building and targeting.
+
+DII refers to a user's normalized email address or phone number, or the normalized and SHA-256-hashed email address or phone number.
+
+![Advertiser Flow](images/advertiser-flow-mermaid.png)
+
+<!-- diagram source: resource/advertiser-flow-mermaid.md.bak -->
+
 
-At a high level, the steps for advertisers and data providers integrating with UID2 are as follows:
+## Detailed Steps
+
+The steps for advertisers and data providers integrating with UID2 by calling the HTTP endpoints are given in the following sections:
 
 1. Generate a raw UID2 from <Link href="../ref-info/glossary-uid#gl-dii">directly identifying information (DII)</Link>, or receive UID2s from another UID2 participant such as a data provider acting on your behalf.
 
-1. Use the UID2s you received in Step 1. For example, you might do one or more of the following:
+    **Instructions**: see [Retrieve a raw UID2 for DII](#retrieve-a-raw-uid2-for-dii).
+
+2. Use the UID2s you received in Step 1. For example, you might do one or more of the following:
    - Do some manipulation: for example, combine UID2s you generated from DII and UID2s received from another participant such as an advertiser or data provider.
    - Add new UID2s into an existing audience.
 
-1. Use the raw UID2s for some purpose such as measurement.
+    **Instructions**: This step is is out of band and entirely up to you.
 
-## Integration Diagram
+3. Use the raw UID2s for some purpose such as:
+   - Send stored raw UID2s to DSPs to create audiences and conversions.
+   - Use the raw UID2s for measurement.
 
-The following diagram outlines the steps that data collectors must complete to map DII to raw UID2s for audience building and targeting.
+    **Instructions**: see [Send stored raw UID2s to DSPs to create audiences or conversions](#send-stored-raw-uid2s-to-dsps-to-create-audiences-or-conversions).
 
-DII refers to a user's normalized email address or phone number, or the normalized and SHA-256-hashed email address or phone number.
+4.	Store the raw UID2 and the salt bucket ID returned from the identity mapping service.
 
-![Advertiser Flow](images/advertiser-flow-mermaid.png)
+    **Instructions**: This step is is out of band and entirely up to you.
 
-<!-- diagram source: resource/advertiser-flow-mermaid.md.bak -->
+5.	Monitor for salt bucket rotations related to your stored raw UID2s.
+
+    **Instructions**: See [Monitor for salt bucket rotations related to your stored raw UID2s](integration-advertiser-dataprovider-overview.md#monitor-for-salt-bucket-rotations-related-to-your-stored-raw-uid2s).
+
+6.	Periodically, monitor for opt-out status, to be sure that you don't continue using UID2s for users that have recently opted out.
 
-Refer to the following sections for details about the different parts of the diagram:
-1. [Retrieve a raw UID2 for DII](#1-retrieve-a-raw-uid2-for-dii)
-2. [Send stored raw UID2s to DSPs to create audiences or conversions](#2-send-stored-raw-uid2s-to-dsps-to-create-audiences-or-conversions)
-3. [Monitor for salt bucket rotations related to your stored raw UID2s](#3-monitor-for-salt-bucket-rotations-related-to-your-stored-raw-uid2s)
+    **Instructions**: See [Check Opt-Out Status](#check-opt-out-status).
 
-### 1: Retrieve a raw UID2 for DII
+### Retrieve a raw UID2 for DII
 
 | Step | Endpoint | Description |
 | --- | --- | --- |
 | 1-a | [POST&nbsp;/identity/map](../endpoints/post-identity-map.md) request | Send a request containing DII to the identity mapping endpoint. |
-| 1-b | [POST&nbsp;/identity/map](../endpoints/post-identity-map.md) response | The `advertising_id` (raw UID2) returned in the response can be used to target audiences on relevant DSPs.<br/>The response returns a user's raw UID2 and the corresponding `bucket_id` for the salt bucket. The salt assigned to the bucket rotates annually, which impacts the generated raw UID2. For details on how to check for salt bucket rotation, see [3: Monitor for salt bucket rotations](#3-monitor-for-salt-bucket-rotations-related-to-your-stored-raw-uid2s).<br/>For ease of maintenance, a recommended approach is to store a user's raw UID2 and `bucket_id` in a mapping table. For guidance on incremental updates, see [Use an incremental process to continuously update raw UID2s](#use-an-incremental-process-to-continuously-update-raw-uid2s). |
+| 1-b | [POST&nbsp;/identity/map](../endpoints/post-identity-map.md) response | The `advertising_id` (raw UID2) returned in the response can be used to target audiences on relevant DSPs.<br/>The response returns a user's raw UID2 and the corresponding `bucket_id` for the salt bucket. The salt assigned to the bucket rotates annually, which impacts the generated raw UID2. For details on how to check for salt bucket rotation, see [3: Monitor for salt bucket rotations](monitor-for-salt-bucket-rotations-related-to-your-stored-raw-uid2s).<br/>For ease of maintenance, a recommended approach is to store a user's raw UID2 and `bucket_id` in a mapping table. For guidance on incremental updates, see [Use an incremental process to continuously update raw UID2s](#use-an-incremental-process-to-continuously-update-raw-uid2s). |
 
-### 2: Send stored raw UID2s to DSPs to create audiences or conversions
+### Send stored raw UID2s to DSPs to create audiences or conversions
 
 Send the `advertising_id` (raw UID2) returned in Step 1-b to a DSP while building your audiences. Each DSP has a unique integration process for building audiences; follow the integration guidance provided by the DSP for sending raw UID2s to build an audience.
 
-### 3: Monitor for salt bucket rotations related to your stored raw UID2s
+### Monitor for salt bucket rotations related to your stored raw UID2s
 A raw UID2 is an identifier for a user at a specific moment in time. The raw UID2 for a specific user changes at least once per year, as a result of the salt rotation. 
 
 Even though each salt bucket is updated approximately once per year, individual bucket updates are spread over the year. Approximately 1/365th of all salt buckets are rotated daily.
@@ -66,21 +82,21 @@ To help ensure that your integration has the current raw UID2s, check salt bucke
 
 | Step | Endpoint | Description |
 | --- | --- | --- |
-| 3-a | [POST&nbsp;/identity/buckets](../endpoints/post-identity-buckets.md) | Send a request to the bucket status endpoint for all salt buckets that have changed since a specific timestamp. |
-| 3-b | [POST&nbsp;/identity/buckets](../endpoints/post-identity-buckets.md) | UID2 service: The bucket status endpoint returns a list of `bucket_id` and `last_updated` timestamps. |
-| 3-c | [POST&nbsp;/identity/map](../endpoints/post-identity-map.md) | Compare the returned `bucket_id` to the salt buckets of raw UID2s that you've cached.<br/>If you find that the salt bucket was updated for one or more raw UID2s, re-send the DII to the identity mapping service for a new raw UID2. |
-| 3-d | [POST&nbsp;/identity/map](../endpoints/post-identity-map.md) | Store the new values returned for `advertising_id` and `bucket_id`. |
+| 5-a | [POST&nbsp;/identity/buckets](../endpoints/post-identity-buckets.md) | Send a request to the bucket status endpoint for all salt buckets that have changed since a specific timestamp. |
+| 5-b | [POST&nbsp;/identity/buckets](../endpoints/post-identity-buckets.md) | UID2 service: The bucket status endpoint returns a list of `bucket_id` and `last_updated` timestamps. |
+| 5-c | [POST&nbsp;/identity/map](../endpoints/post-identity-map.md) | Compare the returned `bucket_id` to the salt buckets of raw UID2s that you've cached.<br/>If you find that the salt bucket was updated for one or more raw UID2s, re-send the DII to the identity mapping service for a new raw UID2. |
+| 5-d | [POST&nbsp;/identity/map](../endpoints/post-identity-map.md) | Store the new values returned for `advertising_id` and `bucket_id`. |
 
 ## Use an Incremental Process to Continuously Update Raw UID2s
 
 To keep your UID2-based audience information accurate and up to date, follow these integration steps every day:
 
-1. The response from the [UID2 retrieval step](#1-retrieve-a-raw-uid2-for-dii) contains mapping information. Cache the following:
+1. The response from the [UID2 retrieval step](#retrieve-a-raw-uid2-for-dii) contains mapping information. Cache the following:
    - The mapping between DII (`identifier`), raw UID2 (`advertising_id`), and salt bucket (`bucket_id`).
    - The most recent `last_updated` timestamp.
-2. Using the results from Step 3, [Monitor for salt bucket rotations related to your stored raw UID2s](#3-monitor-for-salt-bucket-rotations-related-to-your-stored-raw-uid2s), remap any raw UID2 for which the salt buckets have been rotated by retrieving new raw UID2 for those IDs, following Step 1, [Retrieve a raw UID2 for DII](#1-retrieve-a-raw-uid2-for-dii).
+2. Using the results from Step 3, [Monitor for salt bucket rotations related to your stored raw UID2s](monitor-for-salt-bucket-rotations-related-to-your-stored-raw-uid2s), remap any raw UID2 for which the salt buckets have been rotated by retrieving new raw UID2 for those IDs, following Step 1, [Retrieve a raw UID2 for DII](#retrieve-a-raw-uid2-for-dii).
 
-   Then, use the refreshed UID2s to update audiences or conversions, following Step 2, [send raw UID2 to a DSP](#2-send-stored-raw-uid2s-to-dsps-to-create-audiences-or-conversions).
+   Then, use the refreshed UID2s to update audiences or conversions, following Step 2, [send raw UID2 to a DSP](#send-stored-raw-uid2s-to-dsps-to-create-audiences-or-conversions).
 
 ## Check Opt-Out Status
 

docs/guides/integration-advertiser-dataprovider-overview.md

@@ -76,22 +76,23 @@ DII refers to a user's normalized email address or phone number, or the normaliz
 <!-- diagram source: resource/advertiser-flow-mermaid.md.bak -->
 
 Refer to the following sections for details about the different parts of the diagram:
-1. [Retrieve a raw UID2 for DII](#1-retrieve-a-raw-uid2-for-dii)
-2. [Send stored raw UID2s to DSPs to create audiences or conversions](#2-send-stored-raw-uid2s-to-dsps-to-create-audiences-or-conversions)
-3. [Monitor for salt bucket rotations related to your stored raw UID2s](#3-monitor-for-salt-bucket-rotations-related-to-your-stored-raw-uid2s)
+1. [Retrieve a raw UID2 for DII](#retrieve-a-raw-uid2-for-dii)
+2. [Send stored raw UID2s to DSPs to create audiences or conversions](#send-stored-raw-uid2s-to-dsps-to-create-audiences-or-conversions)
+3. [Monitor for salt bucket rotations related to your stored raw UID2s](monitor-for-salt-bucket-rotations-related-to-your-stored-raw-uid2s)
 
-### 1: Retrieve a raw UID2 for DII
+### Retrieve a raw UID2 for DII
 
 | Step | Endpoint | Description |
 | --- | --- | --- |
 | 1-a | [POST&nbsp;/identity/map](../endpoints/post-identity-map.md) request | Send a request containing DII to the identity mapping endpoint. |
-| 1-b | [POST&nbsp;/identity/map](../endpoints/post-identity-map.md) response | The `advertising_id` (raw UID2) returned in the response can be used to target audiences on relevant DSPs.<br/>The response returns a user's raw UID2 and the corresponding `bucket_id` for the salt bucket. The salt assigned to the bucket rotates annually, which impacts the generated raw UID2. For details on how to check for salt bucket rotation, see [3: Monitor for salt bucket rotations](#3-monitor-for-salt-bucket-rotations-related-to-your-stored-raw-uid2s).<br/>For ease of maintenance, a recommended approach is to store a user's raw UID2 and `bucket_id` in a mapping table. For guidance on incremental updates, see [Use an incremental process to continuously update raw UID2s](#use-an-incremental-process-to-continuously-update-raw-uid2s). |
+| 1-b | [POST&nbsp;/identity/map](../endpoints/post-identity-map.md) response | The `advertising_id` (raw UID2) returned in the response can be used to target audiences on relevant DSPs.<br/>The response returns a user's raw UID2 and the corresponding `bucket_id` for the salt bucket. The salt assigned to the bucket rotates annually, which impacts the generated raw UID2. For details on how to check for salt bucket rotation, see [3: Monitor for salt bucket rotations](monitor-for-salt-bucket-rotations-related-to-your-stored-raw-uid2s).<br/>For ease of maintenance, a recommended approach is to store a user's raw UID2 and `bucket_id` in a mapping table. For guidance on incremental updates, see [Use an incremental process to continuously update raw UID2s](#use-an-incremental-process-to-continuously-update-raw-uid2s). |
 
-### 2: Send stored raw UID2s to DSPs to create audiences or conversions
+### Send stored raw UID2s to DSPs to create audiences or conversions
 
 Send the `advertising_id` (raw UID2) returned in Step 1-b to a DSP while building your audiences. Each DSP has a unique integration process for building audiences; follow the integration guidance provided by the DSP for sending raw UID2s to build an audience.
 
-### 3: Monitor for salt bucket rotations related to your stored raw UID2s
+### Monitor for salt bucket rotations related to your stored raw UID2s
+
 A raw UID2 is an identifier for a user at a specific moment in time. The raw UID2 for a specific user changes at least once per year, as a result of the salt rotation. 
 
 Even though each salt bucket is updated approximately once per year, individual bucket updates are spread over the year. Approximately 1/365th of all salt buckets are rotated daily.
@@ -111,12 +112,12 @@ To help ensure that your integration has the current raw UID2s, check salt bucke
 
 To keep your UID2-based audience information accurate and up to date, follow these integration steps every day:
 
-1. The response from Step 1, [Retrieve a raw UID2 for DII](#1-retrieve-a-raw-uid2-for-dii), contains mapping information. Cache the following:
+1. The response from Step 1, [Retrieve a raw UID2 for DII](#retrieve-a-raw-uid2-for-dii), contains mapping information. Cache the following:
    - The mapping between DII (`identifier`), raw UID2 (`advertising_id`), and salt bucket (`bucket_id`).
    - The most recent `last_updated` timestamp.
-2. Using the results from Step 3, [Monitor for salt bucket rotations related to your stored raw UID2s](#3-monitor-for-salt-bucket-rotations-related-to-your-stored-raw-uid2s):
-   1. Remap any raw UID2 for which the salt buckets have been rotated by retrieving new raw UID2 for those IDs, following Step 1, [Retrieve a raw UID2 for DII](#1-retrieve-a-raw-uid2-for-dii).
-   2. Use the refreshed UID2s to update audiences or conversions, following Step 2, [Send stored raw UID2s to DSPs to create audiences or conversions](#2-send-stored-raw-uid2s-to-dsps-to-create-audiences-or-conversions).
+2. Using the results from Step 3, [Monitor for salt bucket rotations related to your stored raw UID2s](monitor-for-salt-bucket-rotations-related-to-your-stored-raw-uid2s):
+   1. Remap any raw UID2 for which the salt buckets have been rotated by retrieving new raw UID2 for those IDs, following Step 1, [Retrieve a raw UID2 for DII](#retrieve-a-raw-uid2-for-dii).
+   2. Use the refreshed UID2s to update audiences or conversions, following Step 2, [Send stored raw UID2s to DSPs to create audiences or conversions](#send-stored-raw-uid2s-to-dsps-to-create-audiences-or-conversions).
 
 ## Check Opt-Out Status