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]

ParameterTypeValue
pidint32Your Placement ID.
itint32The identifier type of the call:
- "4" corresponds to hashed emails.
- "11" corresponds to phone number hashes.
- "15" corresponds to custom IDs. Learn more about Custom IDs Support.
ivstringThe hashed version of the raw email or phone number.

When using custom IDs, you must pass the following values within the iv parameter:

ANA_ID:CUSTOM_ID

ANA_ID represents the Account ID (provided by LiveRamp) whereas CUSTOM_ID represents the custom identifier.
ctint32The type of consent passed to the API.
- "4" represents a TCF v2 consent string for EU/EEA traffic.
- "3" represents a CCPA consent string for U.S. traffic (optional).
cvstringThe consent string. See Step 2: Provide a Valid Consent String for examples.
HeaderTypeValue
originstringAn origin domain that was included in the privacy review for the Placement ID you're using.

🚧

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 --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'

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}]}

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:

Status CodeResponse
200Good response
204No Consent: Opted out user, or opted out browser (if DNT:1 and/or Sec-GPC:1 is sent in the request)
400Bad Request: Bad Config ID (calling non-existent PID), Unexpected (missing) parameter.
401Unauthorized: Origin not allowed (the domain was not approved for this Placement ID ).
403Forbidden: Endpoint not configured for service.
451Unavailable for Legal Reasons: Disallowed country and/or invalid consent string.