Skip to main content

POST /identity/map

Map multiple email addresses or email address hashes to their raw EUIDs 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.

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 or email address 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 map personal data consecutively.
  • Be sure to store mappings of email addresses or email address hashes.
    Not storing mappings may increase processing time drastically when you have to map millions of emails addresses. Recalculating only those mappings that actually need to be updated, however, reduces the total processing time because only about 1/365th of raw EUIDs 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'

IMPORTANT: You must encrypt all request using your secret. For details and Python script examples, see Encrypting Requests and Decrypting Responses.

Path Parameters

Path ParameterData TypeAttributeDescription
{environment}stringRequiredTesting environment: https://integ.euid.eu
Production environment: https://prod.euid.eu
For a full list, including regional operators, 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 two conditional parameters as a key-value pair in the JSON body of the request when encrypting it.

Body ParameterData TypeAttributeDescription
emailstring arrayConditionally RequiredThe list of email addresses to be mapped.
email_hashstring arrayConditionally RequiredThe list of Base64-encoded SHA-256 hashes of normalized email addresses.

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":[
"eVvLS/Vg+YZ6+z3i0NOpSXYyQAfEXqCZ7BTpAjFUBUc=",
"tMmiiTI7IaAcPpQPFQ65uMVCWH8av9jw4cwf/F5HVRQ="
]
}

Here's an encrypted identity mapping request format with placeholder values:

echo '[Unencrypted-JSON-Request-Body]' \
| encrypt_request.py [CLIENT_SECRET] \
| curl -X POST 'https://prod.euid.eu/v2/identity/map' -H 'Authorization: Bearer [CLIENT_API_KEY]' -d @- \
| decrypt_response.py [CLIENT_SECRET]

Here's an encrypted identity mapping request example for email addresses:

echo '{"email": ["user@example.com", "user2@example.com"]}' \
| encrypt_request.py DELPabG/hsJsZk4Xm9Xr10Wb8qoKarg4ochUdY9e+Ow= \
| curl -X POST 'https://prod.euid.eu/v2/identity/map' -H 'Authorization: Bearer YourTokenBV3tua4BXNw+HVUFpxLlGy8nWN6mtgMlIk=' -d @- \
| decrypt_response.py DELPabG/hsJsZk4Xm9Xr10Wb8qoKarg4ochUdY9e+Ow=

For details and Python script examples, 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 EUIDs and salt bucket IDs for the specified email addresses or email address hashes.

{
"body":{
"mapped": [
{
"identifier": "eVvLS/Vg+YZ6+z3i0NOpSXYyQAfEXqCZ7BTpAjFUBUc=",
"advertising_id": "AdvIvSiaum0P5s3X/7X8h8sz+OhF2IG8DNbEnkWSbYM=",
"bucket_id": "a30od4mNRd"
},
{
"identifier": "tMmiiTI7IaAcPpQPFQ65uMVCWH8av9jw4cwf/F5HVRQ=",
"advertising_id": "IbW4n6LIvtDj/8fCESlU0QG9K/fH63UdcTkJpAG8fIQ=",
"bucket_id": "ad1ANEmVZ"
}
]
},
"status":"success"
}

Response Body Properties

PropertyData TypeDescription
identifierstringThe email address or email address hash specified in the request body.
advertising_idstringThe corresponding advertising ID (raw EUID).
bucket_idstringThe ID of the salt bucket used to generate the EUID.

Response Status Codes

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

StatusHTTP Status CodeDescription
success200The request was successful. The response will be encrypted.
client_error400The request had missing or invalid parameters.
unauthorized401The 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.