API Grammar and Clarity Edits

README.md

@@ -1,99 +1,14 @@
-# Unified ID 2.0 API Documentation
+# UID 2.0
 
-## Table Of Contents
-* [Overview](#overview)
-* [Environment](#environment)
-* [Authentication](#authentication)
-* [Error Codes](#error-codes)
-* [Email Normalization](#email-normalization)
-* [Encoding Query Parameter Values](#encode-query-parameter-values)
-* [Endpoints](#endpoints)
-* [Integration Workflows](#integration-workflows)
-* [License](#license)
+| [Click here to visit the UID 2.0 API Documentation](/api/README.md)
 
+## Introduction
 
-## Overview
+Addressable advertising enables publishers and developers to provide the content and services consumers have come to enjoy, whether through mobile apps, streaming TV, or web experiences. This value exchange of the open internet has not always been well understood by, or communicated to, consumers. As the industry reduces reliance on the third-party cookie, we have an opportunity to move towards a new and better approach to identity for the open internet. This improved approach empowers content creators to have the value exchange conversations with consumers while giving them more control and transparency over their data. 
 
-**Building a better foundation for identity on the open internet**
+Unified ID 2.0 (UID2) is a deterministic identifier based on PII (e.g., email or phone number) with complete user transparency and privacy controls. The UID2 identifier ties logged-in experiences from publisher websites, mobile apps, and CTV apps. With several layers of security and privacy measures, UID2s safely distribute across the open internet. Initially built by The Trade Desk, responsibility for UID2 will transfer in mid-2021 to independent organizations for open-source code management, governance, administration, and system operations. UID2 is non-proprietary and accessible to constituents across the advertising ecosystem - including Advertisers, Publishers, DSPs, SSPs, SSOs, CDPs, CMPs, Identity Providers, Data Providers, and Measurement Providers - while they remain in compliance with a code of conduct.
 
-Addressable advertising enables publishers and developers to provide the content and services consumers have come to enjoy, whether through mobile apps, streaming TV, or web experiences. The value exchange of the open internet has not always been well understood by, or communicated to, consumers. As the industry reduces reliance on the third-party cookie, we have an opportunity to move towards a new and better approach to identity for the open internet. The improved approach empowers content creators to have value exchange conversations with consumers while giving them more control and transparency over their data. 
-
-Unified ID 2.0 (UID2) is a deterministic identifier based on authenticated PII (e.g., email or phone number) with complete user transparency and privacy controls. The UID2 identifier ties to logged-in experiences applied to publisher websites, mobile apps, and CTV apps. With several layers of privacy protection, UID2s can safely distribute across the open internet. Initially built by The Trade Desk, operational responsibility for UID2 will transfer in mid-2021 to an independent organization. The independent organization will open-source the relevant code. UID2 is non-proprietary and accessible to constituents across the advertising ecosystem - including Advertisers, Publishers, DSPs, SSPs, SSOs, CDPs, CMPs, Identity Providers, Data Providers, and Measurement Providers - while they remain in compliance with a code of conduct. 
-
-UID2’s goal is to enable deterministic identity for advertising opportunities on the open internet with full consumer transparency and controls. UID2 provides a collaborative framework for all constituents and a healthy, open internet by utilizing a transparent and interoperable approach. 
-
-**Guiding Principles**
-
-+ Independently Governed: UID2 will be operated by unbiased organizations, with the transition from The Trade Desk to independent governance anticipated mid-2021. The Trade Desk built the framework and code to transition to the independent governing body. 
-+ Interoperable: UID2 is accessible to all constituents in the advertising ecosystem who abide by the code of conduct. This includes DSPs, SSPs, data providers, measurement providers, and identity services. 
-+ Open Source: UID2 is transparent and offers its code open-source.   
-+ Nonproprietary: UID2 provides a collaborative framework for all constituents in the advertising ecosystem who are willing to comply with a code of conduct. 
-+ Secure and Privacy-Safe: UID2 leverages multiple layers of security, cryptography, and encryption to ensure user PII and data is safe. 
-+ Transparency and Consent: Users understand where their ID is shared and what data is associated with it. Users have control to revoke their consent and permissions. 
-
-**Contact Info**
-
-If you want to contact the relevant team at The Trade Desk to access UID2, please use the email aliases below. Note that this is only temporary, and when the system moves to independent governance access will be through various industry groups.
-+  UID2publishers@thetradedesk.com - If you are a publisher or developer
-+  UID2partners@thetradedesk.com - If you are a brand, agency, data provider, DSP, SSP, CDP, or related company
-
-## Environment 
-
-All UID2 endpoints use the same base URL.
-
-| Environment | Base URL |
-| --- | --- |
-| Testing | ```https://integ.uidapi.com/v1``` |
-
-e.g. https://integ.uidapi.com/v1/token/generate
-
-## Authentication
-
-Authenticate to UID2 endpoints using a bearer token in the request's authorization header. Contact %placeholder% to request a bearer token.
-
-```Authorization: Bearer YourTokenBV3tua4BXNw+HVUFpxLlGy8nWN6mtgMlIk=```
-
-## Email Normalization
-
-When sending email addresses in a request, normalize email addresses prior to sending.
-
-1. Remove leading and trailing spaces.
-2. Remove `.` (ASCII code 46) from the username of the email address. `jane.doe@example.com` normalizes to `janedoe@example.com`.
-3. Remove `+` (ASCII code 43) and all subsequent characters from the username of the email address. `janedoe+home@example.com` normalizes to `janedoe@example.com`.
-4. Convert all ASCII characters to lowercase.
-
-## Encoding Query Parameter Values
-
-When passing query parameter values in with a request, ensure the query parameter value is URL-encoded. Use Javascript's `encodeURIcomponent()` or your coding language's equivalent.
-
-## Response Structure and Status Codes
-
-All endpoints return responses utilizing the following body and status messaging structure. The `status` property may include endpoint-specific values. The `message` property returns additional information for non-`success` statuses.
-
-```json
-{
-    "status": [success|unauthorized|client_error|...]
-    "body": {
-        "property": "propertyValue"
-    }
-    "message": "Descriptive message"
-}
-```
-
-| Status | HTTP Status Code | Additional Notes |
-| --- | --- | --- |
-| `success` | 200 | |
-| `optout` | 200 | This status only returns for authorized requests. The user opted out. |
-| `client_error` | 400 | See the `message` field for more information about missing or invalid parameters. |
-| `invalid_token` | 400 | This status only returns for authorized requests. The request specified an invalid identity token. |
-| `unauthorized` | 401 | The request did not include a bearer token, included an invalid bearer token, or included a bearer token unauthorized to perform the requested action. |
-
-## Endpoints
-
-[Click here to view an endpoint listing.](/v1/endpoints/README.md)
-
-## Integration Guides
-See Integration guides [here.](/v1/guides/README.md)
+UID2’s goal is to enable deterministic identity for advertising opportunities on the open internet with consumer transparency and controls. UID2 provides a collaborative framework for all constituents and a healthy, open internet by utilizing a transparent and interoperable approach.
 
 ## License
-All work, articafts are licensed under the Apache License, Version 2.0. See [LICENSE](http://www.apache.org/licenses/LICENSE-2.0.txt) for the full license text.
+All work and artifacts are licensed under the Apache License, Version 2.0. See [LICENSE](http://www.apache.org/licenses/LICENSE-2.0.txt) for the full license text.

api/README.md

@@ -0,0 +1,106 @@
+# Unified ID 2.0 API Documentation
+
+## Table Of Contents
+* [Overview](#overview)
+* [Contact Info](#contact-info)
+* [Environment](#environment)
+* [Authentication](#authentication)
+* [Email Normalization](#email-normalization)
+* [Encoding Query Parameter Values](#encoding-query-parameter-values)
+* [Response Structure and Status Codes](#response-structure-and-status-codes)
+* [Endpoints](#endpoints)
+* [Integration Guides](#integration-guides)
+* [License](#license)
+
+
+## Overview
+
+**Building a better foundation for identity on the open internet**
+
+Addressable advertising enables publishers and developers to provide the content and services consumers have come to enjoy, whether through mobile apps, streaming TV, or web experiences. The value exchange of the open internet has not always been well understood by, or communicated to, consumers. As the industry reduces reliance on the third-party cookie, we have an opportunity to move towards a new and better approach to identity for the open internet. The improved approach empowers content creators to have value exchange conversations with consumers while giving them more control and transparency over their data. 
+
+Unified ID 2.0 (UID2) is a deterministic identifier based on authenticated PII (e.g., email or phone number) with complete user transparency and privacy controls. The UID2 identifier ties to logged-in experiences applied to publisher websites, mobile apps, and CTV apps. With several layers of privacy protection, UID2s can safely distribute across the open internet. Initially built by The Trade Desk, operational responsibility for UID2 will transfer in mid-2021 to an independent organization. The independent organization will open-source the relevant code. UID2 is non-proprietary and accessible to constituents across the advertising ecosystem - including Advertisers, Publishers, DSPs, SSPs, SSOs, CDPs, CMPs, Identity Providers, Data Providers, and Measurement Providers - while they remain in compliance with a code of conduct. 
+
+UID2’s goal is to enable deterministic identity for advertising opportunities on the open internet with full consumer transparency and controls. UID2 provides a collaborative framework for all constituents and a healthy, open internet by utilizing a transparent and interoperable approach. 
+
+**Guiding Principles**
+
++ Independently Governed: UID2 will be operated by unbiased organizations, with the transition from The Trade Desk to independent governance anticipated mid-2021. The Trade Desk built the framework and code to transition to the independent governing body. 
++ Interoperable: UID2 is accessible to all constituents in the advertising ecosystem who abide by the code of conduct. This includes DSPs, SSPs, data providers, measurement providers, and identity services. 
++ Open Source: UID2 is transparent and offers its code open-source.   
++ Nonproprietary: UID2 provides a collaborative framework for all constituents in the advertising ecosystem who are willing to comply with a code of conduct. 
++ Secure and Privacy-Safe: UID2 leverages multiple layers of security, cryptography, and encryption to ensure user PII and data is safe. 
++ Transparency and Control: Users understand where their ID is shared and what data is associated with it. Users have control to revoke their consent and permissions. 
+
+## Contact Info
+
+For access to UID2, contact the relevant team at The Trade Desk shown below. Contacting The Trade Desk for access is temporary. When the system moves to independent governance, the governing organizations will handle access requests.
+
+| If you are a... | Contact Email |
+| --- | --- |
+| App Developer<br>Publisher | UID2publishers@thetradedesk.com |
+| Agency<br>Brand<br>CDP<br>Data Provider<br>DSP<br>SSP | UID2partners@thetradedesk.com |
+
+## Environment 
+
+All UID2 endpoints use the same base URL.
+
+| Environment | Base URL |
+| --- | --- |
+| Testing | ```https://integ.uidapi.com/v1``` |
+
+e.g. https://integ.uidapi.com/v1/token/generate
+
+## Authentication
+
+Authenticate to UID2 endpoints using a bearer token in the request's authorization header. 
+
+```Authorization: Bearer YourTokenBV3tua4BXNw+HVUFpxLlGy8nWN6mtgMlIk=```
+
+## Email Normalization
+
+When sending email addresses in a request, normalize email addresses prior to sending.
+
+1. Remove leading and trailing spaces.
+2. Convert all ASCII characters to lowercase.
+
+For email accounts ending in gmail.com:
+
+1. Remove `.` (ASCII code 46) from the username of the email address. `jane.doe@gmail.com` normalizes to `janedoe@gmail.com`.
+2. Remove `+` (ASCII code 43) and all subsequent characters from the username of the email address. `janedoe+home@gmail.com` normalizes to `janedoe@gmail.com`.
+
+## Encoding Query Parameter Values
+
+When passing query parameter values in with a request, ensure the query parameter value is URL-encoded. Use Javascript's `encodeURIcomponent()` or your coding language's equivalent.
+
+## Response Structure and Status Codes
+
+All endpoints return responses utilizing the following body and status messaging structure. The `status` property may include endpoint-specific values. The `message` property returns additional information for non-`success` statuses.
+
+```json
+{
+    "status": [success|unauthorized|client_error|...]
+    "body": {
+        "property": "propertyValue"
+    }
+    "message": "Descriptive message"
+}
+```
+
+| Status | HTTP Status Code | Additional Notes |
+| --- | --- | --- |
+| `success` | 200 | |
+| `optout` | 200 | This status only returns for authorized requests. The user opted out. |
+| `client_error` | 400 | See the `message` field for more information about missing or invalid parameters. |
+| `invalid_token` | 400 | This status only returns for authorized requests. The request specified an invalid identity token. |
+| `unauthorized` | 401 | The request did not include a bearer token, included an invalid bearer token, or included a bearer token unauthorized to perform the requested action. |
+
+## Endpoints
+
+[Click here to view an endpoint listing.](./v1/endpoints/README.md)
+
+## Integration Guides
+[Click here to view integration guides.](./v1/guides/README.md)
+
+## License
+All work and artifacts are licensed under the Apache License, Version 2.0. See [LICENSE](http://www.apache.org/licenses/LICENSE-2.0.txt) for the full license text.

v1/endpoints/README.md → api/v1/endpoints/README.md

@@ -1,4 +1,4 @@
-[UID2 Documentation](../../README.md) > v1 > Endpoints
+[UID2 API Documentation](../../README.md) > v1 > Endpoints
 
 # Endpoints
 
@@ -9,7 +9,6 @@
 | [GET /token/generate](./get-token-generate.md) | Generate a UID2 token from an email address or hashed email address. |
 | [GET /token/validate](./get-token-validate.md) | Validate that an advertising token matches the provided email or email hash. |
 | [GET /token/refresh](./get-token-refresh.md) | Generate a new token for a user by specifying their refresh_token from GET /token/generate. |
-|                                                |                                                              |
 
 ## Identity Maps
 

api/v1/endpoints/get-identity-buckets.md

@@ -0,0 +1,53 @@
+[UID2 API Documentation](../../README.md) > v1 > [Endpoints](./README.md) > GET /identity/buckets
+
+# GET /identity/buckets
+
+Monitor for rotated salt buckets. No salt buckets will be rotated until September 1, 2021. The `body` will return empty until rotations on September 1, 2021 or after.
+
+Integration workflows that use this endpoint:
+* [Advertiser/Data Provider](../guides/advertiser-dataprovider-guide.md)
+
+## Request 
+
+```GET '{environment}/{version}/identity/buckets?{queryParameter}={queryParameterValue}'```
+
+###  Query Parameters
+
+| Query Parameter | Data Type | Attributes | Description |
+| --- | --- | --- | --- |
+| `since_timestamp` | `date-time` or `integer` | Required | Return buckets with last updated UTC timestamps after the specified date and time.<br>Specify the the time in ISO 8601 `date-time` format (`YYYY-MM-DDThh:mm:ss`). Ensure the parameter value is URL encoded. |
+
+#### Example Request
+
+```curl
+curl -L -X GET 'https://integ.uidapi.com/v1/identity/buckets?since_timestamp=2021-03-01T01%3A01%3A01' -H 'Authorization: Bearer YourTokenBV3tua4BXNw+HVUFpxLlGy8nWN6mtgMlIk='
+```
+
+## Response
+
+The endpoint returns a list of ```bucket_id``` and their last updated timestamps.
+
+```json
+{
+    "body":[
+        {
+            "bucket_id":"a3pPl64opk",
+            "last_updated":"2021-03-01T00:00:00"
+        },
+        {
+            "bucket_id":"aENdq9K3VQ",
+            "last_updated":"2021-03-01T00:00:00"
+        },
+        {
+            "bucket_id":"adVEM9ywVo",
+            "last_updated":"2021-03-01T00:00:00"
+        }
+    ],
+    "status":"success"
+}
+```
+
+| Property | Format | Description |
+| --- | --- | --- |
+| `bucket_id` | `string` | The bucket_id associated to the timestamp. |
+| `last_Updated` | `date-time` | The UTC timestamp of the last time the bucket salt was rotated in ISO 8601 format (`YYYY-MM-DDThh:mm:ss`) |

api/v1/endpoints/get-identity-map.md

@@ -0,0 +1,56 @@
+[UID2 API Documentation](../../README.md) > v1 > [Endpoints](./README.md) > GET /identity/map
+
+# GET /identity/map
+
+Retrieve advertising and bucket IDs for one `email` or `email_hash`.
+
+Integration workflows that use this endpoint:
+* [Advertiser/Data Provider](../guides/advertiser-dataprovider-guide.md)
+
+## Request 
+
+```GET '{environment}/{version}/identity/map?{queryParameter}={queryParameterValue}'```
+
+###  Query Parameters
+
+| Query Parameter | Data Type | Attributes | Description |
+| --- | --- | --- | --- |
+| `email` | `string` | Conditionally Required | The [normalized email address](../../README.md#emailnormalization) of a user. Required when `email_hash` is not included in the request. |
+| `email_hash` | `string` | Conditionally Required | The base64-encoded SHA256 hash of the [normalized email address](../../README.md#emailnormalization) of a user. Required when `email` is not included in the request. |
+
+If `email` and `email_hash` are both supposed in the same request, only the `email` will return a mapping response.
+
+#### Example Request Using an Email Address
+
+```sh
+curl -L -X GET 'https://integ.uidapi.com/v1/identity/map?email=username@example.com' -H 'Authorization: Bearer YourTokenBV3tua4BXNw+HVUFpxLlGy8nWN6mtgMlIk='
+```
+
+#### Example Request Using an Email Hash
+
+```sh
+curl -L -X GET 'https://integ.uidapi.com/v1/identity/map?email_hash=eVvLS%2FVg%2BYZ6%2Bz3i0NOpSXYyQAfEXqCZ7BTpAjFUBUc%3D' -H 'Authorization: Bearer YourTokenBV3tua4BXNw+HVUFpxLlGy8nWN6mtgMlIk='
+```
+
+## Response
+
+The response is a JSON object containing the user's UID2 identifier and bucket identifier.
+
+```json
+{
+    "body": {
+            "identifier": "username@example.com",
+            "advertising_id": "AdvtiSuYWAZSYe8t4n6sQx0gshoHYZdOzg9qUn/eKgE=",
+            "bucket_id": "bucketId"
+        },
+    "status":"success"
+}
+```
+
+## Body Response Properties
+
+| Property | Data Type | Description |
+| --- | --- | --- |
+| `body.identifier` | `string` | The `email` or `email_hash` provided in the request. |
+| `body.advertising_id` | `string` | The identity's advertising ID (raw UID2). |
+| `body.bucket_id` | `string` | The identifier of the bucket used for salting the user's `advertising_id`. |