Retrieving Envelope Endpoints

Common identifiers

The most common identifiers for the ATS API are hashed emails. The endpoint accepts common hash types of emails:

• MD5
• SHA1
• SHA256

In order to obtain the best possible envelope for a user, we recommend calling the API with all three email hash types. If you are only able to hash or obtain one, we prefer SHA1.

In the US, the ATS API also supports hashed phone numbers. Only SHA1 hashes should be passed for phone numbers.

If you are calling the ATS API for European Union internet traffic, a valid consent string with LiveRamp listed as a vendor for all five purposes is required. The consent string parameters are not required in other geographies.

Ensure that you follow our data pre-processing and hashing guidelines provided here.

Responses

Provided you have submitted a well-formed query to the ATS API, two types of "successful" responses are possible.

For opted-in users, you will receive 200 response for a JSON object with a simple key/value containing the envelope:

{"envelope":"Ao42jiiUNWfvloyXY887EBn801otRTWYnklvjCtw9REF_TMoMWLkeUvzVmQVZG1q"}

If the user is opted-out, you will receive a 204 response with no content.

Error states are described above.

Required Javascript Interface

In order to provide your envelope to other parties on the web, for example, using Prebid.js, you must implement a mock function and expose it where you are resolving users to envelopes.

Other Javascript running on page should be able to make a call to window.ats.retrieveEnvelope() and receive a JSON object, e.g.:

{"envelope":"AtkoTqF8plPFYr2r2QgpbhKhY_XWhJrmI0gSSTulk24dzDKTlNOf4A"}

If no envelope is available, return undefined

Assuming you store the envelope in a cookie called _lr_env, the below function will look up the envelope (if it exists) and return it to the caller.

function mockEnvelope() {
  try {
    var env = JSON.stringify({
      "envelope": document.cookie.match('(^|;) *_lr_env=([^;]*)')[2]
    });
    return env || undefined;
  } catch (e) {
    return undefined
  }
}

window['ats'] = {};
window.ats.retrieveEnvelope = mockEnvelope;