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]
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.
Parameters | Type | Value |
---|---|---|
pid | int32 | Your Placement ID. |
it | int32 | The envelope type of the call: - "19" corresponds to regular ATS envelopes. - "24" corresponds to Facebook-scoped envelopes. |
cv | 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. |
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 --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'
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.
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.
Updated 7 days ago