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.

🚧
Make sure to only call the LiveRamp API with a positive consent string for users in the EU.

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

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]&atype=[source call]

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).You may use the`gpp_sid` parameter instead for U.S. users.
`gpp_sid`	string	The valid corresponding GPP section ID which specifies the GPP consent string type. They are as follows: "7" represents a US-National string "8" represents a California string "9" represents a Virginia string "10" represents a Colorado string "11" represents a Utah string "12" represents a Connecticut string "13" represents a Florida string "14" represents a Montana string "15" represents a Oregon string "16" represents a Texas string "17" represents a Delaware string "19" represents a Nebraska string "20" represents a New Hampshire string "21" represents a New Jersey string "22" represents a Tennessee string
`cv`	string	The consent string for TCF v2 and CCPA. See Step 2: Provide a Valid Consent String for examples. You may use the `gpp` parameter instead for U.S. users.
`gpp`	string	The GPP consent string.
`atype`	string	The ATS implementation method to determine source of envelope call. "1" represents ATS.js "2" represents ATS API "3" represents server-to-server implementation "4" represents ATS Mobile SDK

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'

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]&atype=[source call]

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":"Aqs3wtOuqIRic78_s4Nqilcr0MGn0cDvKzvpEhSGVjwV8Ci0Jy73B1bkfpv03GwK2uyKbME4kSAtVFn_5sCLWstyHTnEWYurbjLXLpgtf9MfLP1AeDTUQ_0ESnD3x1pr6gYfBOOUH8BPhbfscxdaGUA-_sacPab3nzc05koLhbqrJIQC7JBraEbpOJPDAHp9f44DXIXm","err":null},{"type":25,"source":"pairIds","value":"WyJBeVhiNUF0dmsvVS8xQ1d2ejJuRVk5aFl4T1g3TVFPUTJVQk1BMFdiV1ZFbSJd","err":null}]}

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

`"type"`	`"source"`	Product
19	`envelopeLiveramp`	ATS
24	`envelopeSource200`	Meta Conversions API
25	`pairIds`	PAIR
26	`atsDirect`	ATS Direct
27	`envelopeLiverampRTB`	Google SSP

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.