Skip to content

Commit 4bb0bbf

Browse files
sophia-chen-ttdsophia-chen-ttd
committed
initial update of identity map docs with v3 fields
1 parent a4c487c commit 4bb0bbf

File tree

1 file changed

+62
-81
lines changed

1 file changed

+62
-81
lines changed

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

Lines changed: 62 additions & 81 deletions
Original file line numberDiff line numberDiff line change
@@ -9,9 +9,10 @@ import Link from '@docusaurus/Link';
99

1010
# POST /identity/map
1111

12-
[**TO BE UPDATED. VERSION SECTION ADDED BUT THE REST NEEDS UPDATING**]
13-
14-
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.
12+
Maps multiple email addresses, phone numbers, or their respective hashes to their raw UID2s. You can also use this endpoint to:
13+
* check for updates opt-out information
14+
* check when an advertisting ID may be refreshed
15+
* map the previous advertising ID for advertising IDs that are less than 90 days old
1516

1617
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).
1718

@@ -55,57 +56,57 @@ The integration environment and the production environment require different <Li
5556
### Unencrypted JSON Body Parameters
5657

5758
:::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+
You can include one or more of the following four parameters as a key-value pair in the JSON body of the request when encrypting it.
5960
:::
6061

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. |
62+
| Body Parameter | Data Type | Attribute | Description |
63+
| :--- |:-----------------| :--- | :--- |
64+
| `email` | DII object array | Conditionally Required | The list of email addresses to be mapped. |
65+
| `email_hash` | DII object 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. |
66+
| `phone` | DII object array | Conditionally Required | The list of [normalized](../getting-started/gs-normalization-encoding.md#phone-number-normalization) phone numbers to be mapped. |
67+
| `phone_hash` | DII object 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. |
68+
69+
#### DII Object
70+
Each DII i.e. email address, email hash, phone or phone hash is input as a DII object.
71+
72+
| DII Object Parameter | Data Type | Attribute | Description |
73+
| :--- | :---- | :---- |:------------|
74+
| `i` | string | Required | The DII input i.e. email address, email hash, phone or phone hash
6775

6876
### Request Examples
6977

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:
78+
The following are unencrypted JSON request body examples to the `POST /identity/map` endpoint:
7179

7280
```json
7381
{
7482
"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-
{
83+
{"i": "[email protected]"},
84+
{"i": "[email protected]"}
85+
],
9086
"phone":[
91-
"+12345678901",
92-
"+441234567890"
87+
{"i": "+12345678901"},
88+
{"i": "+441234567890"}
9389
]
9490
}
9591
```
92+
9693
```json
9794
{
95+
"email_hash":[
96+
{"i": "tMmiiTI7IaAcPpQPFQ65uMVCWH8av9jw4cwf/F5HVRQ="},
97+
{"i": "KzsrnOhCq4tqbGFMsflgS7ig1QLRr0nFJrcrEIlOlbU="}
98+
],
9899
"phone_hash":[
99-
"EObwtHBUqDNZR33LNSMdtt5cafsYFuGmuY4ZLenlue4=",
100-
"Rx8SW4ZyKqbPypXmswDNuq0SPxStFXBTG/yvPns/2NQ="
100+
{"i": "EObwtHBUqDNZR33LNSMdtt5cafsYFuGmuY4ZLenlue4="},
101+
{"i": "Rx8SW4ZyKqbPypXmswDNuq0SPxStFXBTG/yvPns/2NQ="}
101102
]
102103
}
103104
```
104105

105106
Here's an encrypted request example to the `POST /identity/map` endpoint for a phone number:
106107

107108
```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+
echo '{"phone": [{"i": "+12345678901"}, {"i": "+441234567890"}]}' | python3 uid2_request.py https://prod.uidapi.com/v3/identity/map [Your-Client-API-Key] [Your-Client-Secret]
109110
```
110111

111112
For details, and code examples in different programming languages, see [Encrypting Requests and Decrypting Responses](../getting-started/gs-encryption-decryption.md).
@@ -116,83 +117,63 @@ For details, and code examples in different programming languages, see [Encrypti
116117
The response is encrypted only if the HTTP status code is 200. Otherwise, the response is not encrypted.
117118
:::
118119

119-
A successful decrypted response returns the raw UID2s for the specified email addresses, phone numbers, or their respective hashes.
120+
A successful decrypted response returns the raw UID2s for the specified email addresses, phone numbers, or their respective hashes in the same array order that was given.
120121

121122
```json
122123
{
123124
"body":{
124-
"mapped": [
125+
"email": [
125126
{
126-
"identifier": "EObwtHBUqDNZR33LNSMdtt5cafsYFuGmuY4ZLenlue4=",
127-
"advertising_id": "AdvIvSiaum0P5s3X/7X8h8sz+OhF2IG8DNbEnkWSbYM=",
128-
"bucket_id": "a30od4mNRd"
127+
"u": "AdvIvSiaum0P5s3X/7X8h8sz+OhF2IG8DNbEnkWSbYM=",
128+
"p": null,
129+
"r": 1735689600000
129130
},
130131
{
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"
132+
"u": "IbW4n6LIvtDj/8fCESlU0QG9K/fH63UdcTkJpAG8fIQ=",
133+
"p": null,
134+
"r": 1735862400000
151135
}
152136
],
153-
"unmapped": [
154-
{
155-
"identifier": "some@malformed@email@hash",
156-
"reason": "invalid identifier"
157-
}
158-
]
137+
"email_hash": [],
138+
"phone": [],
139+
"phone_hash": []
159140
},
160141
"status":"success"
161142
}
162143
```
163144

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".
145+
Identifiers that cannot be mapped to an advertising ID are mapped to an error object with the reason for unsuccessful mapping. This will occur if the identifier is considered invalid or if the identifier has opted out from the UID2 ecosystem. In these cases, the response status is still "success".
165146

166147
```json
167148
{
168149
"body":{
169-
"mapped": [
170-
{
171-
"identifier": "EObwtHBUqDNZR33LNSMdtt5cafsYFuGmuY4ZLenlue4=",
172-
"advertising_id": "AdvIvSiaum0P5s3X/7X8h8sz+OhF2IG8DNbEnkWSbYM=",
173-
"bucket_id": "a30od4mNRd"
174-
}
150+
"email": [
151+
{ "e": "INVALID" },
152+
{ "e": "OPTOUT" }
175153
],
176-
"unmapped": [
177-
{
178-
"identifier": "tMmiiTI7IaAcPpQPFQ65uMVCWH8av9jw4cwf/F5HVRQ=",
179-
"reason": "optout"
180-
}
181-
]
154+
"email_hash": [],
155+
"phone": [],
156+
"phone_hash": []
182157
},
183158
"status":"success"
184159
}
185160
```
186161

187162
### Response Body Properties
188163

189-
The response body includes the properties shown in the following table.
164+
For successfully mapped DIIs, the response body includes the properties shown in the following table.
190165

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-
| `TODO` | string | TODO: NEW VALUES |
166+
| Property | Data Type | Description |
167+
|:---------|:---------------|:--------------------------------------------------------------------------------------------------------------------------------------|
168+
| `u` | string | The advertising ID (raw UID2) of the DII given in the request. |
169+
| `p` | string or null | The previous advertising ID if the current ID has been refreshed in the last 90 days. `null` if the current ID is older than 90 days. |
170+
| `r` | number | The Unix timestamp (in milliseconds) that indicates when the advertising ID may be refreshed. |
171+
172+
For unsuccessfully mapped DIIs, the response body includes the properties shown in the following table.
173+
174+
| Property | Data Type | Description |
175+
|:---------|:----------|:-----------------------------------------------------------------------------------------------|
176+
| `e` | string | The reason for being unable to map the DII to an advertising ID. One of: "OPTOUT", "INVALID". |
196177

197178
### Response Status Codes
198179

0 commit comments

Comments
 (0)