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]
Parameter | Type | Value |
---|---|---|
pid | int32 | Your Placement ID. |
it | int32 | The 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. |
iv | string | The 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. |
ct | int32 | The 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). |
cv | string | The consent string. See Step 2: Provide a Valid Consent String for examples. |
Header | Type | Value |
---|---|---|
origin | string | An 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 Code | Response |
---|---|
200 | Good response |
204 | No Consent: Opted out user, or opted out browser (if DNT:1 and/or Sec-GPC:1 is sent in the request) |
400 | Bad Request: Bad Config ID (calling non-existent PID), Unexpected (missing) parameter. |
401 | Unauthorized: Origin not allowed (the domain was not approved for this Placement ID ). |
403 | Forbidden: Endpoint not configured for service. |
451 | Unavailable for Legal Reasons: Disallowed country and/or invalid consent string. |
Updated 12 days ago