7. Implement the ATS Refresh Envelope API

Refreshing envelopes is an important step to keep the match rate as high as possible for your users.

Existing envelopes can be exchanged for fresh envelopes by calling:

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

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

This will reset the envelope expiration to the maximum allowed value after which you need to store the newly obtained envelope and update the timestamp in storage.

The response should contain fresh envelopes tied to the same identifiers.

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

Check out our API Reference page to help you generate the call.

🚧

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

curl --request GET \
     --url 'https://api.rlcdn.com/api/identity/v2/envelope/refresh?pid=14&it=19&iv=Alkc6LgKZzbqHvexyq4hyzxp0zQZnIztut2rFKjmcDtSBbM0rttk5pH2qb8iNkyxCO9kYAKg6oM2rt28dbWV6-lt9BxwoPCabDaOUXN3fr2C1qsCeV9H0qcW3wBPbbnTpxFWI0Wnh7WVPFYrCM8FgziDEBwSoYnUMO9wheayikvFSGX3Qsz1lr0QWnj2dHEMhx5V2QEbhkJ2iwH2zLEaKAt5oVa8EwAf59mOQepN3S_CwQk4C5OkgfZYiUXTYwxpDA&ct=4&cv=CPUCbs9PUDXghADABCENCBCoAP_AAEJAAAAADGwBAAGABPADCAY0BjYAgADAAngBhAMaAAA.YAAAAAAAA4AA' \
     --header 'Origin: https://example.com' \
     --header 'X-Forwarded-For: 203.0.113.195' \
     --header 'accept: application/json'

📘

Retrieving and Refreshing Envelopes

Envelopes are returned when you pass hashed emails or phone numbers to the ATS envelope endpoint. This can happen when a user visits your website for the first time, or the first time they visit after a couple of months.

When you refresh that envelope, you instead provide the value of the envelope to the ATS refresh endpoint. This returns a new envelope that is still tied to the same identifier. This can happen when for example the user makes multiple visits to your website at the same day. Rather than making a new signal, envelope refresh allows you to use the same one that is refreshed and valid.

The ATS refresh endpoint was designed to be consistent with the behaviour of ATS for Web which stores identity envelopes rather than identifiers, thus can only accept envelope values to refresh them.

When to Call the Refresh API

We highly recommend calling the Refresh Envelope API on the first subsequent page load after a user authenticates and again every 30 minutes when a user enters a new page or refreshes the current page.

When setting a timestamp, you can look at the value of the timestamp to determine when exactly you need to refresh the envelopes.

Refreshing an Expired Envelope

When you call the Refresh Envelope API on an expired envelope; you will receive a 204 response. In this case, you'll need to discard the expired envelope and fetch another envelope with the ATS Envelope API.