ATS
Changelog
Back to All
added

Introducing Version 2 of the ATS API Endpoint

almost 3 years ago

We have released an enhanced version of the ATS API endpoint, designed to handle multiple types of identity envelopes more effectively and efficiently.

About ATS API Version 2

The new endpoint has the following advantages:

  • Ability to return ATS identity envelopes, Facebook-scoped envelopes, and PAIR IDs with a single envelope retrieval request
  • Google PAIR support - Google PAIR can only be implemented with ATS if you are calling V2 of the ATS API
  • Enhanced API response formatting which includes error messaging and envelope type
  • Ability to refresh an ATS and a Facebook-scoped envelope in a single API request, reducing calls and latency
  • Improved debugging efficiency for our support team from the reduced API calls

The New Endpoints

To retrieve ATS envelopes (and other types of envelopes), call the following endpoint:

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

To refresh ATS envelopes, call the following endpoint:

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

Response Examples

If you're only running ATS, the response will only contain an identity envelope if a positive consent signal is detected. If you've implemented the Facebook Conversion API Adapter, the response will contain a Facebook-scoped envelope alongside the ATS identity envelope:

{"envelopes":[{"type":19,"source":"envelopeLiveramp","value":"Alkc6LgKZzbqHvexyq4hyzxp0zQZnIztut2rFKjmcDtSBbM0rttk5pH2qb8iNkyxCO9kYAKg6oM2rt28dbWV6-lt9BxwoPCabDaOUXN3fr2C1qsCeV9H0qcW3wBPbbnTpxFWI0Wnh7WVPFYrCM8FgziDEBwSoYnUMO9wheayikvFSGX3Qsz1lr0QWnj2dHEMhx5V2QEbhkJ2iwH2zLEaKAt5oVa8EwAf59mOQepN3S_CwQk4C5OkgfZYiUXTYwxpDA","err":null},{"type":24,"source":"envelopeSource200","value":"BeEQ_c7DOKeu8XVIRImTEPB_qgHapbMhOo_zfVkhtJmD08omJsfnHOmAS_TK90J1k62hpwElJrDIkkVfC7lHgUmauzizRh5qAPRe8IBKAeMW0TW2RRFjxWk","err":null}]}

If you've implemented Google PAIR, the response may contain a PAIR ID (or more) alongside the ATS identity envelope:

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

To learn more see Facebook CAPI Adapter and Google PAIR.

Working With the Previous API Endpoints

Currently, you can still use the previous version of the endpoint without any repercussions:

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

However, we recommend updating your call to Version 2 so you can take full advantages of the ATS API V2 capabilities. Keep yourself updated by checking the Changelog for any changes in the future.