4. Call the ATS Envelope API

Call the Envelope API with the endpoint below. You can also check out our handy API reference page to help you generate the call.

https://api.rlcdn.com/api/identity/v2/envelope?pid=[placement id]&it=[identifier type]&iv=[hashed identifier]&ct=[consent type]&cv=[consent string]

https://api.rlcdn.com/api/identity/v2/envelope?pid=[placement> id]&it=[identifier type]&iv=[hashed identifier]&gpp=[gpp consent string]&gpp_sid=[gpp section id]

🚧

Server-to-Server Integrations

When retrieving or refreshing the ATS Envelopes, publishers integrating server-to-server are required to include the X-Forwarded-For header to ensure that the client-side IP address is within the approved countries tied to the ATS Placement.

For example:

cURL

curl --request GET \
     --url 'https://api.rlcdn.com/api/identity/v2/envelope?pid=14&it=4&iv=38CFDA7F9B55B7F74B6D3D143CBB7661DA9BFEB4683473A5813B220A571A1E37&ct=4&cv=CPUCbs9PUDXghADABCENCBCoAP_AAEJAAAAADGwBAAGABPADCAY0BjYAgADAAngBhAMaAAA.YAAAAAAAA4AA' \
     --header 'Origin: https://example.com' \
     --header 'X-Forwarded-For: 203.0.113.195' \
     --header 'accept: application/json'

Sending Multiple Hash Types

We recommend sending the identifiers in multiple hash types (SHA256, SHA1, and MD5) to get the best match rate. If you are sending multiple hash types, you will need to use the it and iv values for each hash. The hash type will automatically be determined by our API.

https://api.rlcdn.com/api/identity/v2/envelope?pid=[placement id]&it=[identifier type]&iv=[hashed identifier 1]&it=[identifier type]&iv=[hashed identifier 2]&ct=[consent type]&cv=[consent string]

ATS Envelope API Responses

Provided you have submitted a well-formed query to the ATS Envelope API, two types of "successful" responses are possible.

For opted-in users
You will receive a 200 response for a JSON object containing one or multiple identity envelopes:

{"envelopes":[{"type":19,"source":"envelopeLiveramp","value":"Alkc6LgKZzbqHvexyq4hyzxp0zQZnIztut2rFKjmcDtSBbM0rttk5pH2qb8iNkyxCO9kYAKg6oM2rt28dbWV6-lt9BxwoPCabDaOUXN3fr2C1qsCeV9H0qcW3wBPbbnTpxFWI0Wnh7WVPFYrCM8FgziDEBwSoYnUMO9wheayikvFSGX3Qsz1lr0QWnj2dHEMhx5V2QEbhkJ2iwH2zLEaKAt5oVa8EwAf59mOQepN3S_CwQk4C5OkgfZYiUXTYwxpDA","err":null},{"type":25,"source":"pairIds","value":"WyJ6SU5BVGppTGpaUUJITTNENUtvcUoweTNYdFlsNDZVaDN4bW5aUm9OYlNNSyIsIlllR3MyUTR6eG5Ba0x3b05leDlxSm9vRFhPb3NndUloV1dPWGdITVhFZ0ZtIiwiQXBMdS83OEt0UlkzSnFrdEdUT0JTZkVjclczRWo0b0VWaE16Y1VtRDZ4M2ciLCJBdDBTVlBZalBiMUd4UjlGSFd0SS9xWFFINTRXUFllSTlWelc5MTRFWHJ4VSJd","err":null}]}

You can identify the types of envelopes by looking at the values of "type" and "source" in the response:

For opted-out users (no positive consent signal)
You will receive a 204 response with no content.

See the complete list of status codes below: