Skip to content

Commit afe0ea2

Browse files
aulmeaulme
authored
Merge pull request #899 from IABTechLab/staging-identity-map-v3
Staging identity map v3
2 parents 5511eaf + 7571842 commit afe0ea2

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

44 files changed

+2557
-382
lines changed

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

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

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

17+
:::important
18+
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`.
19+
20+
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).
21+
:::
22+
1723
## Request Format
1824

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

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

Lines changed: 207 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,207 @@
1+
---
2+
title: POST /identity/map (v2)
3+
description: Maps DII to raw UID2s and salt bucket IDs.
4+
hide_table_of_contents: false
5+
sidebar_position: 07
6+
---
7+
8+
import Link from '@docusaurus/Link';
9+
10+
# POST /identity/map (v2)
11+
12+
Maps multiple email addresses, phone numbers, or their respective hashes to their raw UID2s and <Link href="../ref-info/glossary-uid#gl-salt-bucket-id">salt bucket IDs</Link>. You can also use this endpoint to check for updates to opt-out information.
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+
For details about the UID2 opt-out workflow and how users can opt out, see [User Opt-Out](../getting-started/gs-opt-out.md).
17+
18+
## Version
19+
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).
21+
22+
:::note
23+
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).
24+
:::
25+
26+
## Batch Size and Request Parallelization Requirements
27+
28+
Here's what you need to know:
29+
30+
- The maximum request size is 1MB.
31+
- 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.
32+
- 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.
33+
- 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 raw 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).
34+
35+
## Request Format
36+
37+
`POST '{environment}/v2/identity/map'`
38+
39+
For authentication details, see [Authentication and Authorization](../getting-started/gs-auth.md).
40+
41+
:::important
42+
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).
43+
:::
44+
45+
### Path Parameters
46+
47+
| Path Parameter | Data Type | Attribute | Description |
48+
| :--- | :--- | :--- | :--- |
49+
| `{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). |
50+
51+
:::note
52+
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).
53+
:::
54+
55+
### Unencrypted JSON Body Parameters
56+
57+
:::important
58+
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.
59+
:::
60+
61+
| Body Parameter | Data Type | Attribute | Description |
62+
| :--- | :--- | :--- | :--- |
63+
| `email` | string array | Conditionally Required | The list of email addresses to be mapped. |
64+
| `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. |
65+
| `phone` | string array | Conditionally Required | The list of [normalized](../getting-started/gs-normalization-encoding.md#phone-number-normalization) phone numbers to be mapped. |
66+
| `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. |
67+
68+
### Request Examples
69+
70+
The following are unencrypted JSON request body examples for each parameter, one of which you should include in your requests to the `POST /identity/map` endpoint:
71+
72+
```json
73+
{
74+
"email":[
75+
"[email protected]",
76+
"[email protected]"
77+
]
78+
}
79+
```
80+
```json
81+
{
82+
"email_hash":[
83+
"tMmiiTI7IaAcPpQPFQ65uMVCWH8av9jw4cwf/F5HVRQ=",
84+
"KzsrnOhCq4tqbGFMsflgS7ig1QLRr0nFJrcrEIlOlbU="
85+
]
86+
}
87+
```
88+
```json
89+
{
90+
"phone":[
91+
"+12345678901",
92+
"+441234567890"
93+
]
94+
}
95+
```
96+
```json
97+
{
98+
"phone_hash":[
99+
"EObwtHBUqDNZR33LNSMdtt5cafsYFuGmuY4ZLenlue4=",
100+
"Rx8SW4ZyKqbPypXmswDNuq0SPxStFXBTG/yvPns/2NQ="
101+
]
102+
}
103+
```
104+
105+
Here's an encrypted request example to the `POST /identity/map` endpoint for a phone number:
106+
107+
```sh
108+
echo '{"phone": ["+12345678901", "+441234567890"]}' | python3 uid2_request.py https://prod.uidapi.com/v2/identity/map [Your-Client-API-Key] [Your-Client-Secret]
109+
```
110+
111+
For details, and code examples in different programming languages, see [Encrypting Requests and Decrypting Responses](../getting-started/gs-encryption-decryption.md).
112+
113+
## Decrypted JSON Response Format
114+
115+
:::note
116+
The response is encrypted only if the HTTP status code is 200. Otherwise, the response is not encrypted.
117+
:::
118+
119+
A successful decrypted response returns the raw UID2s and salt bucket IDs for the specified email addresses, phone numbers, or their respective hashes.
120+
121+
```json
122+
{
123+
"body":{
124+
"mapped": [
125+
{
126+
"identifier": "EObwtHBUqDNZR33LNSMdtt5cafsYFuGmuY4ZLenlue4=",
127+
"advertising_id": "AdvIvSiaum0P5s3X/7X8h8sz+OhF2IG8DNbEnkWSbYM=",
128+
"bucket_id": "a30od4mNRd"
129+
},
130+
{
131+
"identifier": "Rx8SW4ZyKqbPypXmswDNuq0SPxStFXBTG/yvPns/2NQ=",
132+
"advertising_id": "IbW4n6LIvtDj/8fCESlU0QG9K/fH63UdcTkJpAG8fIQ=",
133+
"bucket_id": "ad1ANEmVZ"
134+
}
135+
]
136+
},
137+
"status":"success"
138+
}
139+
```
140+
141+
If some identifiers are considered invalid, they are included in the response in an "unmapped" list. In this case, the response status is still "success". If all identifiers are mapped, the "unmapped" list is not included in the response.
142+
143+
```json
144+
{
145+
"body":{
146+
"mapped": [
147+
{
148+
"identifier": "EObwtHBUqDNZR33LNSMdtt5cafsYFuGmuY4ZLenlue4=",
149+
"advertising_id": "AdvIvSiaum0P5s3X/7X8h8sz+OhF2IG8DNbEnkWSbYM=",
150+
"bucket_id": "a30od4mNRd"
151+
}
152+
],
153+
"unmapped": [
154+
{
155+
"identifier": "some@malformed@email@hash",
156+
"reason": "invalid identifier"
157+
}
158+
]
159+
},
160+
"status":"success"
161+
}
162+
```
163+
164+
If some identifiers have opted out from the UID2 ecosystem, the opted-out identifiers are moved to the "unmapped" list along with any invalid identifiers found. In this case, the response status is still "success".
165+
166+
```json
167+
{
168+
"body":{
169+
"mapped": [
170+
{
171+
"identifier": "EObwtHBUqDNZR33LNSMdtt5cafsYFuGmuY4ZLenlue4=",
172+
"advertising_id": "AdvIvSiaum0P5s3X/7X8h8sz+OhF2IG8DNbEnkWSbYM=",
173+
"bucket_id": "a30od4mNRd"
174+
}
175+
],
176+
"unmapped": [
177+
{
178+
"identifier": "tMmiiTI7IaAcPpQPFQ65uMVCWH8av9jw4cwf/F5HVRQ=",
179+
"reason": "optout"
180+
}
181+
]
182+
},
183+
"status":"success"
184+
}
185+
```
186+
187+
### Response Body Properties
188+
189+
The response body includes the properties shown in the following table.
190+
191+
| Property | Data Type | Description |
192+
| :--- | :--- | :--- |
193+
| `identifier` | string | The email address, phone number, or respective hash specified in the request body. |
194+
| `advertising_id` | string | The corresponding advertising ID (raw UID2). |
195+
| `bucket_id` | string | The ID of the salt bucket used to generate the raw UID2. |
196+
197+
### Response Status Codes
198+
199+
The following table lists the `status` property values and their HTTP status code equivalents.
200+
201+
| Status | HTTP Status Code | Description |
202+
| :--- | :--- | :--- |
203+
| `success` | 200 | The request was successful. The response will be encrypted. |
204+
| `client_error` | 400 | The request had missing or invalid parameters.|
205+
| `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. |
206+
207+
If the `status` value is anything other than `success`, the `message` field provides additional information about the issue.

0 commit comments

Comments
 (0)