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

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 with a simple key/value containing the envelope:

{"envelope":"Ao42jiiUNWfvloyXY887EBn801otRTWYnklvjCtw9REF_TMoMWLkeUvzVmQVZG1q"}

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/browser.

400

Bad Request: Bad Config ID (calling non-existent PID), Unexpected (missing) parameter.

401

Unauthorized: Origin not allowed (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.