POST /identity/map

Maps multiple email addresses, phone numbers, or their respective hashes to their raw UID2s and salt bucket IDs. You can also use this endpoint to check for updates to opt-out information.

Used by: This endpoint is used mainly by advertisers and data providers. For details, see Advertiser/Data Provider Integration Guide.

For details about the UID2 opt-out workflow and how users can opt out, see User Opt-Out.

Batch Size and Request Parallelization Requirements

Here's what you need to know:

The maximum request size is 1MB.
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.
Unless you are using a Private Operator, do not send batches in parallel. In other words, use a single HTTP connection and send batches of hashed or unhashed directly identifying information (DII) values consecutively, without creating multiple parallel connections.
Be sure to store mappings of email addresses, phone numbers, or their respective hashes.
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 Guide and FAQs for Advertisers and Data Providers.

Request Format

POST '{environment}/v2/identity/map'

For authentication details, see Authentication and Authorization.

important

You must encrypt all requests using your secret. For details, and code examples in different programming languages, see Encrypting Requests and Decrypting Responses.

Path Parameters

Path Parameter	Data Type	Attribute	Description
`{environment}`	string	Required	Testing (integration) environment: `https://operator-integ.uidapi.com` 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.

note

The integration environment and the production environment require different API keys.

Unencrypted JSON Body Parameters

important

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.

Body Parameter	Data Type	Attribute	Description
`email`	string array	Conditionally Required	The list of email addresses to be mapped.
`email_hash`	string array	Conditionally Required	The list of Base64-encoded SHA-256 hashes of normalized email addresses to be mapped.
`phone`	string array	Conditionally Required	The list of normalized phone numbers to be mapped.
`phone_hash`	string array	Conditionally Required	The list of Base64-encoded SHA-256 hashes of normalized phone numbers to be mapped.

Request Examples

The following are unencrypted JSON request body examples for each parameter, one of which you should include in your identity mapping requests:

{
    "email":[
        "user@example.com",
        "user2@example.com"
    ]
}

{
    "email_hash":[
        "tMmiiTI7IaAcPpQPFQ65uMVCWH8av9jw4cwf/F5HVRQ=",
        "KzsrnOhCq4tqbGFMsflgS7ig1QLRr0nFJrcrEIlOlbU="
    ]
}

{
    "phone":[
        "+12345678901",
        "+441234567890"
    ]
}

{
    "phone_hash":[
        "EObwtHBUqDNZR33LNSMdtt5cafsYFuGmuY4ZLenlue4=",
        "Rx8SW4ZyKqbPypXmswDNuq0SPxStFXBTG/yvPns/2NQ="
    ]
}

Here's an encrypted identity mapping request example for a phone number:

echo '{"phone": ["+12345678901", "+441234567890"]}' | python3 uid2_request.py https://prod.uidapi.com/v2/identity/map [Your-Client-API-Key] [Your-Client-Secret]

For details, and code examples in different programming languages, see Encrypting Requests and Decrypting Responses.

Decrypted JSON Response Format

note

The response is encrypted only if the HTTP status code is 200. Otherwise, the response is not encrypted.

A successful decrypted response returns the raw UID2s and salt bucket IDs for the specified email addresses, phone numbers, or their respective hashes.

{
    "body":{
        "mapped": [
            {
                "identifier": "EObwtHBUqDNZR33LNSMdtt5cafsYFuGmuY4ZLenlue4=",
                "advertising_id": "AdvIvSiaum0P5s3X/7X8h8sz+OhF2IG8DNbEnkWSbYM=",
                "bucket_id": "a30od4mNRd"
            },
            {
                "identifier": "Rx8SW4ZyKqbPypXmswDNuq0SPxStFXBTG/yvPns/2NQ=",
                "advertising_id": "IbW4n6LIvtDj/8fCESlU0QG9K/fH63UdcTkJpAG8fIQ=",
                "bucket_id": "ad1ANEmVZ"
            }
        ]
    },
    "status":"success"
}

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.

{
    "body":{
        "mapped": [
            {
                "identifier": "EObwtHBUqDNZR33LNSMdtt5cafsYFuGmuY4ZLenlue4=",
                "advertising_id": "AdvIvSiaum0P5s3X/7X8h8sz+OhF2IG8DNbEnkWSbYM=",
                "bucket_id": "a30od4mNRd"
            }
        ],
        "unmapped": [
            {
                "identifier": "some@malformed@email@hash",
                "reason": "invalid identifier"
            }
        ]
    },
    "status":"success"
}

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".

{
    "body":{
        "mapped": [
            {
                "identifier": "EObwtHBUqDNZR33LNSMdtt5cafsYFuGmuY4ZLenlue4=",
                "advertising_id": "AdvIvSiaum0P5s3X/7X8h8sz+OhF2IG8DNbEnkWSbYM=",
                "bucket_id": "a30od4mNRd"
            }
        ],
        "unmapped": [
            {
                "identifier": "tMmiiTI7IaAcPpQPFQ65uMVCWH8av9jw4cwf/F5HVRQ=",
                "reason": "optout"
            }
        ]
    },
    "status":"success"
}

Response Body Properties

The response body includes the properties shown in the following table.

Property	Data Type	Description
`identifier`	string	The email address, phone number, or respective hash specified in the request body.
`advertising_id`	string	The corresponding advertising ID (raw UID2).
`bucket_id`	string	The ID of the salt bucket used to generate the raw UID2.

Response Status Codes

The following table lists the status property values and their HTTP status code equivalents.

Status	HTTP Status Code	Description
`success`	200	The request was successful. The response will be encrypted.
`client_error`	400	The request had missing or invalid parameters.
`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.

If the status value is anything other than success, the message field provides additional information about the issue.

Batch Size and Request Parallelization Requirements​

Request Format​

Path Parameters​

Unencrypted JSON Body Parameters​

Request Examples​

Decrypted JSON Response Format​

Response Body Properties​

Response Status Codes​