Skip to content

Commit f782545

Browse files
gmsdelmundogmsdelmundo
committed
Cloned changed endpoints files
1 parent e7dd840 commit f782545

7 files changed

Lines changed: 456 additions & 106 deletions

‎docs/endpoints/post-identity-buckets-new.md‎

Lines changed: 115 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,115 @@
1+
---
2+
title: POST /identity/buckets
3+
description: Monitors rotated salt buckets.
4+
hide_table_of_contents: false
5+
sidebar_position: 07
6+
---
7+
8+
import Link from '@docusaurus/Link';
9+
10+
# POST /identity/buckets
11+
12+
Monitors rotated <Link href="../ref-info/glossary-uid#gl-salt-bucket">salt buckets</Link>.
13+
14+
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).
15+
16+
:::important
17+
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`.
18+
19+
If you're using the earlier version, we recommend that you upgrade as soon as possible, to take advantage of improvements.
20+
:::
21+
22+
## Request Format
23+
24+
`POST '{environment}/v2/identity/buckets'`
25+
26+
For authentication details, see [Authentication and Authorization](../getting-started/gs-auth.md).
27+
28+
:::important
29+
You must encrypt all requests using your secret. For details, and code examples in different programming languages, see [Encrypting Requests and Decrypting Responses](../getting-started/gs-encryption-decryption.md).
30+
:::
31+
32+
### Path Parameters
33+
34+
| Path Parameter | Data Type | Attribute | Description |
35+
| :--- | :--- | :--- | :--- |
36+
| `{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). |
37+
38+
:::note
39+
The integration environment and the production environment require different <Link href="../ref-info/glossary-uid#gl-api-key">API keys</Link>. For information about getting credentials for each environment, see [Getting Your Credentials](../getting-started/gs-credentials.md#getting-your-credentials).
40+
:::
41+
42+
### Unencrypted JSON Body Parameters
43+
44+
:::important
45+
You must include the following parameter as a key-value pair in the JSON body of a request when encrypting it.
46+
:::
47+
48+
| Body Parameter | Data Type | Attribute | Description | Format |
49+
| :--- | :--- | :--- | :--- | :--- |
50+
| `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` |
51+
52+
### Request Examples
53+
54+
The following is an unencrypted JSON request body example, which you should include in your identity bucket rotation requests:
55+
56+
```json
57+
{
58+
"since_timestamp": "2022-06-01T13:00:00"
59+
}
60+
```
61+
Here's an encrypted identity bucket rotation request example:
62+
63+
```sh
64+
echo '{"since_timestamp": "2023-04-19T13:00:00"}' | python3 uid2_request.py https://prod.uidapi.com/v2/identity/buckets [Your-Client-API-Key] [Your-Client-Secret]
65+
```
66+
67+
For details, and code examples in different programming languages, see [Encrypting Requests and Decrypting Responses](../getting-started/gs-encryption-decryption.md).
68+
69+
## Decrypted JSON Response Format
70+
71+
:::note
72+
The response is encrypted only if the HTTP status code is 200. Otherwise, the response is not encrypted.
73+
:::
74+
75+
A successful decrypted response returns a list of salt bucket IDs and the timestamps of their last updates.
76+
77+
```json
78+
{
79+
"body":[
80+
{
81+
"bucket_id": "a30od4mNRd",
82+
"last_updated": "2022-06-05T22:52:03.109"
83+
},
84+
{
85+
"bucket_id": "aJ0jMvw9Z8",
86+
"last_updated": "2022-06-06T22:52:01.828"
87+
},
88+
{
89+
"bucket_id": "aeRQ9L7wRN",
90+
"last_updated": "2022-06-01T22:52:02.574"
91+
}
92+
],
93+
"status":"success"
94+
}
95+
```
96+
### Response Body Properties
97+
98+
The response body includes the properties shown in the following table.
99+
100+
| Property | Format | Description |
101+
| :--- | :--- | :--- |
102+
| `bucket_id` | string | The salt bucket ID. |
103+
| `last_updated` | date-time | The UTC timestamp of the last time the bucket salt was rotated. |
104+
105+
### Response Status Codes
106+
107+
The following table lists the `status` property values and their HTTP status code equivalents.
108+
109+
| Status | HTTP Status Code | Description |
110+
| :--- | :--- | :--- |
111+
| `success` | 200 | The request was successful. The response will be encrypted. |
112+
| `client_error` | 400 | The request had missing or invalid parameters. |
113+
| `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 operation. |
114+
115+
If the `status` value is anything other than `success`, the `message` field provides additional information about the issue.

‎docs/endpoints/post-identity-buckets.md‎

Lines changed: 0 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -13,12 +13,6 @@ Monitors rotated <Link href="../ref-info/glossary-uid#gl-salt-bucket">salt bucke
1313

1414
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).
1515

16-
:::important
17-
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`.
18-
19-
If you're using the earlier version, we recommend that you upgrade as soon as possible, to take advantage of improvements.
20-
:::
21-
2216
## Request Format
2317

2418
`POST '{environment}/v2/identity/buckets'`

‎docs/endpoints/post-identity-map-new.md‎

Lines changed: 196 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,196 @@
1+
---
2+
title: POST /identity/map
3+
description: Maps DII to raw UID2s.
4+
hide_table_of_contents: false
5+
sidebar_position: 08
6+
displayed_sidebar: docs
7+
---
8+
9+
import Link from '@docusaurus/Link';
10+
11+
# POST /identity/map
12+
13+
Maps multiple email addresses, phone numbers, or their respective hashes to their raw UID2s. You can also use this endpoint to check for updates to opt-out information, check when a raw UID2 can be refreshed, or view the previous UID2 if the current UID2 is less than 90 days old.
14+
15+
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).
16+
17+
For details about the UID2 opt-out workflow and how users can opt out, see [User Opt-Out](../getting-started/gs-opt-out.md).
18+
19+
## Version
20+
21+
This documentation is for the latest version of this endpoint, version 3.
22+
23+
If needed, documentation is also available for the previous version: see [POST /identity/map (v2)](post-identity-map-v2-new.md).
24+
25+
## Batch Size and Request Parallelization Requirements
26+
27+
Here's what you need to know:
28+
29+
- The maximum request size is 1MB.
30+
- To map a large number of email addresses, phone numbers, or their respective hashes, send them in *sequential* batches with a maximum batch size of 5,000 items per batch.
31+
- Unless you are using a <Link href="../ref-info/glossary-uid#gl-private-operator">Private Operator</Link>, do not send batches in parallel. In other words, use a single HTTP connection and send batches of hashed or unhashed <Link href="../ref-info/glossary-uid#gl-dii">directly identifying information (DII)</Link> values consecutively, without creating multiple parallel connections.
32+
- Be sure to store mappings of email addresses, phone numbers, or their respective hashes.<br/>Not storing mappings could increase processing time drastically when you have to map millions of email addresses or phone numbers. Recalculating only those mappings that actually need to be updated, however, reduces the total processing time because only about 1/365th of UID2s need to be updated daily. See also [Advertiser/Data Provider Integration Overview](../guides/integration-advertiser-dataprovider-overview.md) and [FAQs for Advertisers and Data Providers](../getting-started/gs-faqs.md#faqs-for-advertisers-and-data-providers).
33+
34+
## Request Format
35+
36+
`POST '{environment}/v3/identity/map'`
37+
38+
For authentication details, see [Authentication and Authorization](../getting-started/gs-auth.md).
39+
40+
:::important
41+
You must encrypt all requests using your secret. For details, and code examples in different programming languages, see [Encrypting Requests and Decrypting Responses](../getting-started/gs-encryption-decryption.md).
42+
:::
43+
44+
### Path Parameters
45+
46+
| Path Parameter | Data Type | Attribute | Description |
47+
| :--- | :--- | :--- | :--- |
48+
| `{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). |
49+
50+
:::note
51+
The integration environment and the production environment require different <Link href="../ref-info/glossary-uid#gl-api-key">API keys</Link>. For information about getting credentials for each environment, see [Getting Your Credentials](../getting-started/gs-credentials.md#getting-your-credentials).
52+
:::
53+
54+
### Unencrypted JSON Body Parameters
55+
56+
:::important
57+
Include one or more of the following four parameters as key-value pairs in the JSON body of the request when encrypting it.
58+
:::
59+
60+
| Body Parameter | Data Type | Attribute | Description |
61+
|:---------------|:----------------------------|:-----------------------| :--- |
62+
| `email` | string array | Conditionally Required | The list of email addresses to be mapped. |
63+
| `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. |
64+
| `phone` | string array | Conditionally Required | The list of [normalized](../getting-started/gs-normalization-encoding.md#phone-number-normalization) phone numbers to be mapped. |
65+
| `phone_hash` | string array | Conditionally Required | The list of [Base64-encoded SHA-256](../getting-started/gs-normalization-encoding.md#phone-number-hash-encoding) hashes of [normalized](../getting-started/gs-normalization-encoding.md#phone-number-normalization) phone numbers to be mapped. |
66+
67+
68+
### Request Examples
69+
70+
The following are unencrypted JSON request body examples to the `POST /identity/map` endpoint:
71+
72+
```json
73+
{
74+
"email":[
75+
"user@example.com",
76+
"user2@example.com"
77+
],
78+
"phone":[
79+
"+12345678901",
80+
"+441234567890"
81+
]
82+
}
83+
```
84+
85+
```json
86+
{
87+
"email_hash":[
88+
"tMmiiTI7IaAcPpQPFQ65uMVCWH8av9jw4cwf/F5HVRQ=",
89+
"KzsrnOhCq4tqbGFMsflgS7ig1QLRr0nFJrcrEIlOlbU="
90+
],
91+
"phone_hash":[
92+
"EObwtHBUqDNZR33LNSMdtt5cafsYFuGmuY4ZLenlue4=",
93+
"Rx8SW4ZyKqbPypXmswDNuq0SPxStFXBTG/yvPns/2NQ="
94+
]
95+
}
96+
```
97+
98+
Here's an encrypted request example to the `POST /identity/map` endpoint for a phone number:
99+
100+
```sh
101+
echo '{"phone": ["+12345678901", "+441234567890"]}' | python3 uid2_request.py https://prod.uidapi.com/v3/identity/map [YOUR_CLIENT_API_KEY] [YOUR_CLIENT_SECRET]
102+
```
103+
104+
For details, and code examples in different programming languages, see [Encrypting Requests and Decrypting Responses](../getting-started/gs-encryption-decryption.md).
105+
106+
## Decrypted JSON Response Format
107+
108+
:::note
109+
The response is encrypted only if the HTTP status code is 200. Otherwise, the response is not encrypted.
110+
:::
111+
112+
A successful decrypted response returns the current raw UID2s, previous raw UID2s, and refresh timestamps for the specified email addresses, phone numbers, or their respective hashes.
113+
114+
The response arrays preserve the order of input arrays. Each element in the response array maps directly to the element at the same index in the corresponding request array. This ensures that you can reliably associate results with their corresponding inputs based on array position.
115+
116+
Input values that cannot be mapped to a raw UID2 are mapped to an error object with the reason for unsuccessful mapping. An unsuccessful mapping occurs if the DII is invalid or has been opted out from the UID2 ecosystem. In these cases, the response status is `success` but no raw UID2 is returned.
117+
118+
The following example shows input and response.
119+
120+
Input:
121+
122+
```json
123+
{
124+
"email": [
125+
"user@example.com" // Corresponding UID2 rotated in the last 90 days
126+
"user2@example.com" // Corresponding UID2 rotated more than 90 days ago
127+
"invalid email string" // Invalid identifier
128+
"optout@example.com" // DII is opted out
129+
]
130+
}
131+
```
132+
133+
Response:
134+
135+
```json
136+
{
137+
"body":{
138+
"email": [
139+
{
140+
"u": "AdvIvSiaum0P5s3X/7X8h8sz+OhF2IG8DNbEnkWSbYM=",
141+
"p": "EObwtHBUqDNZR33LNSMdtt5cafsYFuGmuY4ZLenlue4=",
142+
"r": 1735689600000
143+
},
144+
{
145+
"u": "IbW4n6LIvtDj/8fCESlU0QG9K/fH63UdcTkJpAG8fIQ=",
146+
"p": null,
147+
"r": 1735862400000
148+
},
149+
{ "e": "invalid identifier" },
150+
{ "e": "optout" }
151+
],
152+
"email_hash": [],
153+
"phone": [],
154+
"phone_hash": []
155+
},
156+
"status":"success"
157+
}
158+
```
159+
160+
### Response Body Properties
161+
162+
The response body includes one or more of the properties shown in the following table.
163+
164+
| Body Parameter | Data Type | Description |
165+
|:---------------|:----------------------------|:------------------------------------------------------------------------------------------------|
166+
| `email` | array of mapped DII objects | The list of mapped DII objects corresponding to the list of emails in the request. |
167+
| `email_hash` | array of mapped DII objects | The list of mapped DII objects corresponding to the list of email hashes in the request. |
168+
| `phone` | array of mapped DII objects | The list of mapped DII objects corresponding to the list of phone numbers in the request. |
169+
| `phone_hash` | array of mapped DII objects | The list of mapped DII objects corresponding to the list of phone number hashes in the request. |
170+
171+
172+
For successfully mapped DII, the mapped object includes the properties shown in the following table.
173+
174+
| Property | Data Type | Description |
175+
|:---------|:-----------|:--------------------------------------------------------------------------------------------------------------------------------------|
176+
| `u` | string | The raw UID2 corresponding to the email or phone number provided in the request. |
177+
| `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> |
178+
| `r` | number | The Unix timestamp (in milliseconds) that indicates when the raw UID2 can be refreshed. |
179+
180+
For unsuccessfully mapped input values, the mapped object includes the properties shown in the following table.
181+
182+
| Property | Data Type | Description |
183+
|:---------|:----------|:-----------------------------------------------------------------------------------------------------------------|
184+
| `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> |
185+
186+
### Response Status Codes
187+
188+
The following table lists the `status` property values and their HTTP status code equivalents.
189+
190+
| Status | HTTP Status Code | Description |
191+
| :--- | :--- | :--- |
192+
| `success` | 200 | The request was successful. The response will be encrypted. |
193+
| `client_error` | 400 | The request had missing or invalid parameters.|
194+
| `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 operation. |
195+
196+
If the `status` value is anything other than `success`, the `message` field provides additional information about the issue.

docs/endpoints/post-identity-map-v2.md renamed to docs/endpoints/post-identity-map-v2-new.md

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -17,7 +17,7 @@ For details about the UID2 opt-out workflow and how users can opt out, see [User
1717

1818
## Version
1919

20-
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).
20+
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-new.md).
2121

2222
:::note
2323
If you're using the earlier version, we recommend that you upgrade as soon as possible, to take advantage of improvements.

0 commit comments

Comments
 (0)