Banners
Banners are the interface to managing cookies, they are displayed when a visitor loads one of our customer’s websites.
Read (GET)
Overview
Retrieve all banners for the specified query. The query has the following shape:
Request
[ { "account_id": "<string>", "ids": [ "<string>" ] }]
At least 1 object with an account_id
must be provided. If you would like to retrieve all of the banners for the account omit the ids
parameter. If the ids
field is sent it must have 1 or more items. Once constructed the object must be URL encoded and be the value for the query
parameter.
Paging
All GET
requests are subject to paging
Paging Rules
Result sets with more than 25 results will be automatically partitioned into groups, and will follow these rules:
- If not specified, the group size will be 25;
- The group size can be specified along with the query objects;
- The group size is limited to a maximum of 25;
- The group size is limited to a minimum of 1;
The response will contain data that allows paging through the results. The JSON shape is:
{ "next_results": "<string>", "previous_results": "<string>"}
next_results
url to next page in the set (null if there is not a next page)previous_results
url to previous page in the set (null if there is not a previous page)
Paging Parameters Object
It is possible to customize the paging parameters for each query. If you want to customize the settings, include the following object in your request:
{ "group_size": "<number>"}
This will return groups of the specified size. Please note the following rules:
- If not specified, the group size will be 25;
- The group size is limited to a maximum of 25;
- The group size is limited to a minimum of 1;
- If a number outside this range is specified the default will apply
Specifying the custom group sizes
To specify the custom group sizes, include the following object in your request:
[ { "paging": { "group_size": 20 }, "account_id": "<string>", "website_id": "<string>", "ids": [ "<string>" ] }]
Sorting
At this time the API sorts all results in descending order on the creation date so the most recent record is first in the results.
Response
The response has the following shape:
{ "results": [], "errors": [], "scrolling": {}}
The results will contain zero or more of the following objects:
{ "results": [ { "id": "<string>", "account_id": "<string>", "website_id": "<string>", "theme_id": "<string>", "position": "<enum{'bottom', 'bottom_left', 'bottom_right', 'top', 'top_left', 'top_right'}>", "default_theme": "<enum{'blue', 'light', 'green', 'red', 'black', 'navy_blue'}>", "display_style": "<enum{'stretch', 'banner', 'tooltip', 'modal'}>", "size": "<enum{'standard', 'compact'}>", "personalized_content": "<bool>", "running_targeted_advertising": "<bool>", "share_data_to_3rd_party": "<bool>", "selected_languages": ["<enum{'el', 'hu', 'pt', 'sv', 'it', 'es', 'en-gb', 'da', 'fi', 'nl', 'fr', 'de', 'pl'}>"], "regions": { "<enum{'global', 'us', 'california', 'eu'}>": { "enable_banner": "<bool>", "enable_decline_button": "<bool>", "enable_cookie_preference_button": "<bool>", "consent_mode": "<enum{'opt_in', 'opt_out'}>", "enable_consent_by_scroll": "<bool>", "enable_google_consent_mode": "<bool>" "google_consent_mode_settings": { "ad_personalization": "<enum{'denied', 'granted'}>", "ad_storage": "<enum{'denied', 'granted'}>", "ad_user_data": "<enum{'denied', 'granted'}>", "ads_data_redaction": "<bool>", "analytics_storage": "<enum{'denied', 'granted'}>", "enable_wait_for_update": "<bool>", "functionality_storage": "<enum{'denied', 'granted'}>", "personalization_storage": "<enum{'denied', 'granted'}>", "security_storage": "<enum{'denied', 'granted'}>", "social_storage": "<enum{'denied', 'granted'}>", "url_passthrough": "<bool>", "wait_for_update": "<integer>" }, "enable_tcf": "<bool>" } } } ], "errors": [ { "error": "<string>", "account_id": "<string>", } ], "paging": { "next_results": null, "previous_results": null }}
The value of
display_style
affects what is allowed inposition
display_style
ofstretch
allowsposition
bottom
andtop
display_style
ofbanner
allowsposition
bottom
andtop
display_style
oftooltip
allowsposition
bottom_left
,bottom_right
,top_left
andtop_right
display_style
ofmodal
ignores theposition
field
The
size
value may be used with anydisplay_style
US english
en
is required and will be selected by default even ifselected_languages
is set to an empty array
id
is the unique identifier of the website (the website will always and only have 1 banner so use the website id)account_id
is the unique identifier of the accountwebsite_id
is the unique identifier of the websitetheme_id
is the unique identifier for the custom theme, iftheme_id
is nil thendefault_theme
is usedposition
is the position of the Banner*default_theme
is the name of the default theme to be useddisplay_style
is style of the banner*size
is the size of the banner*personalized_content
does the website have content personalized for the user?running_targeted_advertising
are there targeted advertisements on the website?share_data_to_3rd_party
does the Website share data with third parties?selected_languages
languages the banner will auto display in based on regionregions
region specific settings<region name>
name of the region for the specific settingsenable_banner
is the banner enabled?enable_decline_button
is the user allowed to decline consent?enable_cookie_preference_button
show the Cookie Preference Button in the banner?consent_mode
does the user need to opt in or opt out of consent?enable_consent_by_scroll
is a user scrolling accepted as consent?enable_google_consent_mode
is google consent mode enabled?google_consent_mode_settings
is an object containing the google consent mode settingsad_personalization
Sets consent for personalized advertising.ad_storage
Enables storage (such as cookies) related to advertising.ad_user_data
Sets consent for sending user data related to advertising to Google.ads_data_redaction
To further redact your ads data when ad_storage is denied, set ads_data_redaction to true.analytics_storage
Enables storage (such as cookies) related to analytics e.g. visit duration.enable_wait_for_update
Should wait_for_update be enabledfunctionality_storage
Enables storage that supports the functionality of the website or app e.g. language settings.personalization_storage
Enables storage related to personalization e.g. video recommendationssecurity_storage
Enables storage related to security such as authentication functionality, fraud prevention, and other user protection.social_storage
Enables storage related to socialurl_passthrough
Pass through ad click, client ID, and session ID information in URLswait_for_update
How long (in milliseconds) to wait before data is sent
enable_tcf
is IAB TCF enabled? NOTE: This can only be set in the EU region.
Example 1
Request banner for a single website.
Request
GET https://api.termly.io/v1/websites/banners?query=%5B%0A%20%20%7B%0A%20%20%20%20%22account_id%22%3A%20%22acct_1234%22%2C%0A%20%20%20%20%22ids%22%3A%20%5B%22web_1234%22%5D%0A%20%20%7D%0A%5D
Query
[ { "account_id": "acct_1234", "ids": ["web_1234"] }]
Response
{ "results": [ { "id": "web_1234", "account_id": "acct_1234", "theme_id": "cct_1234", "position": "bottom", "default_theme": "navy_blue", "display_style": "banner", "size": "standard", "personalized_content": true, "running_targeted_advertising": false, "share_data_to_3rd_party": true, "selected_languages": ["en", "pl"], "regions": { "global": { "enable_banner": true, "enable_decline_button": false, "enable_cookie_preference_button": true, "consent_mode": "opt_out", "enable_consent_by_scroll": true, "enable_google_consent_mode": false, "google_consent_mode_settings": { "ad_personalization": "denied", "ad_storage": "denied", "ad_user_data": "denied", "ads_data_redaction": false, "analytics_storage": "denied", "enable_wait_for_update": false, "functionality_storage": "denied", "personalization_storage": "denied", "security_storage": "denied", "social_storage": "denied", "url_passthrough": false, "wait_for_update": 500 } }, "us": { "enable_banner": true, "enable_decline_button": false, "enable_cookie_preference_button": true, "consent_mode": "opt_out", "enable_consent_by_scroll": true, "enable_google_consent_mode": false, "google_consent_mode_settings": { "ad_personalization": "denied", "ad_storage": "denied", "ad_user_data": "denied", "ads_data_redaction": false, "analytics_storage": "denied", "enable_wait_for_update": false, "functionality_storage": "denied", "personalization_storage": "denied", "security_storage": "denied", "social_storage": "denied", "url_passthrough": false, "wait_for_update": 500 } }, "california": { "enable_banner": true, "enable_decline_button": false, "enable_cookie_preference_button": true, "consent_mode": "opt_out", "enable_consent_by_scroll": true, "enable_google_consent_mode": false, "google_consent_mode_settings": { "ad_personalization": "denied", "ad_storage": "denied", "ad_user_data": "denied", "ads_data_redaction": false, "analytics_storage": "denied", "enable_wait_for_update": false, "functionality_storage": "denied", "personalization_storage": "denied", "security_storage": "denied", "social_storage": "denied", "url_passthrough": false, "wait_for_update": 500 } }, "eu": { "enable_banner": true, "enable_decline_button": false, "enable_cookie_preference_button": true, "consent_mode": "opt_out", "enable_consent_by_scroll": true, "enable_google_consent_mode": false, "google_consent_mode_settings": { "ad_personalization": "denied", "ad_storage": "denied", "ad_user_data": "denied", "ads_data_redaction": false, "analytics_storage": "denied", "enable_wait_for_update": false, "functionality_storage": "denied", "personalization_storage": "denied", "security_storage": "denied", "social_storage": "denied", "url_passthrough": false, "wait_for_update": 500 }, "enable_tcf": false } } } ], "errors": [], "paging": { "next_results": null, "previous_results": null }}
Example 2
Request banners for multiple websites on the same account.
Request
GET https://api.termly.io/v1/websites/banners?query=%5B%0A%20%20%7B%0A%20%20%20%20%22account_id%22%3A%20%22acct_1234%22%2C%0A%20%20%7D%2C%0A%20%20%7B%0A%20%20%20%20%22account_id%22%3A%20%22acct_1234%22%2C%0A%20%20%7D%2C%0A%20%20%7B%0A%20%20%20%20%22account_id%22%3A%20%22acct_1234%22%2C%0A%20%20%7D%0A%5D
Query
[ { "account_id": "acct_1234", }, { "account_id": "acct_1234", }, { "account_id": "acct_1234", }]
Response
{ "results": [ { "id": "web_1234", "account_id": "acct_1234", "theme_id": "cct_1234", "position": "bottom", "default_theme": "navy_blue", "display_style": "banner", "size": "standard", "personalized_content": true, "running_targeted_advertising": false, "share_data_to_3rd_party": true, "selected_languages": ["en", "pl"], "regions": { "global": { "enable_banner": true, "enable_decline_button": false, "enable_cookie_preference_button": true, "consent_mode": "opt_out", "enable_consent_by_scroll": true, "enable_google_consent_mode": false, "google_consent_mode_settings": { "ad_personalization": "denied", "ad_storage": "denied", "ad_user_data": "denied", "ads_data_redaction": false, "analytics_storage": "denied", "enable_wait_for_update": false, "functionality_storage": "denied", "personalization_storage": "denied", "security_storage": "denied", "social_storage": "denied", "url_passthrough": false, "wait_for_update": 500 } }, "us": { "enable_banner": true, "enable_decline_button": false, "enable_cookie_preference_button": true, "consent_mode": "opt_out", "enable_consent_by_scroll": true, "enable_google_consent_mode": false, "google_consent_mode_settings": { "ad_personalization": "denied", "ad_storage": "denied", "ad_user_data": "denied", "ads_data_redaction": false, "analytics_storage": "denied", "enable_wait_for_update": false, "functionality_storage": "denied", "personalization_storage": "denied", "security_storage": "denied", "social_storage": "denied", "url_passthrough": false, "wait_for_update": 500 } }, "california": { "enable_banner": true, "enable_decline_button": false, "enable_cookie_preference_button": true, "consent_mode": "opt_out", "enable_consent_by_scroll": true, "enable_google_consent_mode": false, "google_consent_mode_settings": { "ad_personalization": "denied", "ad_storage": "denied", "ad_user_data": "denied", "ads_data_redaction": false, "analytics_storage": "denied", "enable_wait_for_update": false, "functionality_storage": "denied", "personalization_storage": "denied", "security_storage": "denied", "social_storage": "denied", "url_passthrough": false, "wait_for_update": 500 } }, "eu": { "enable_banner": true, "enable_decline_button": false, "enable_cookie_preference_button": true, "consent_mode": "opt_out", "enable_consent_by_scroll": true, "enable_google_consent_mode": false, "google_consent_mode_settings": { "ad_personalization": "denied", "ad_storage": "denied", "ad_user_data": "denied", "ads_data_redaction": false, "analytics_storage": "denied", "enable_wait_for_update": false, "functionality_storage": "denied", "personalization_storage": "denied", "security_storage": "denied", "social_storage": "denied", "url_passthrough": false, "wait_for_update": 500 }, "enable_tcf": true } } }, { "id": "web_5678", "account_id": "acct_1234", "theme_id": "cct_5678", "position": "bottom", "default_theme": "navy_blue", "display_style": "banner", "size": "compact", "personalized_content": true, "running_targeted_advertising": false, "share_data_to_3rd_party": true, "selected_languages": ["en", "pl"], "regions": { "global": { "enable_banner": true, "enable_decline_button": false, "enable_cookie_preference_button": true, "consent_mode": "opt_out", "enable_consent_by_scroll": true, "enable_google_consent_mode": false, "google_consent_mode_settings": { "ad_personalization": "denied", "ad_storage": "denied", "ad_user_data": "denied", "ads_data_redaction": false, "analytics_storage": "denied", "enable_wait_for_update": false, "functionality_storage": "denied", "personalization_storage": "denied", "security_storage": "denied", "social_storage": "denied", "url_passthrough": false, "wait_for_update": 500 } }, "us": { "enable_banner": true, "enable_decline_button": false, "enable_cookie_preference_button": true, "consent_mode": "opt_out", "enable_consent_by_scroll": true, "enable_google_consent_mode": false, "google_consent_mode_settings": { "ad_personalization": "denied", "ad_storage": "denied", "ad_user_data": "denied", "ads_data_redaction": false, "analytics_storage": "denied", "enable_wait_for_update": false, "functionality_storage": "denied", "personalization_storage": "denied", "security_storage": "denied", "social_storage": "denied", "url_passthrough": false, "wait_for_update": 500 } }, "california": { "enable_banner": true, "enable_decline_button": false, "enable_cookie_preference_button": true, "consent_mode": "opt_out", "enable_consent_by_scroll": true, "enable_google_consent_mode": false, "google_consent_mode_settings": { "ad_personalization": "denied", "ad_storage": "denied", "ad_user_data": "denied", "ads_data_redaction": false, "analytics_storage": "denied", "enable_wait_for_update": false, "functionality_storage": "denied", "personalization_storage": "denied", "security_storage": "denied", "social_storage": "denied", "url_passthrough": false, "wait_for_update": 500 } }, "eu": { "enable_banner": true, "enable_decline_button": false, "enable_cookie_preference_button": true, "consent_mode": "opt_out", "enable_consent_by_scroll": true, "enable_google_consent_mode": false, "google_consent_mode_settings": { "ad_personalization": "denied", "ad_storage": "denied", "ad_user_data": "denied", "ads_data_redaction": false, "analytics_storage": "denied", "enable_wait_for_update": false, "functionality_storage": "denied", "personalization_storage": "denied", "security_storage": "denied", "social_storage": "denied", "url_passthrough": false, "wait_for_update": 500 }, "enable_tcf": false } } }, { "id": "web_2112", "account_id": "acct_1234", "theme_id": "cct_2112", "position": "bottom", "default_theme": "navy_blue", "display_style": "banner", "size": "compact", "personalized_content": true, "running_targeted_advertising": false, "share_data_to_3rd_party": true, "selected_languages": ["en", "pl"], "regions": { "global": { "enable_banner": true, "enable_decline_button": false, "enable_cookie_preference_button": true, "consent_mode": "opt_out", "enable_consent_by_scroll": true, "enable_google_consent_mode": false, "google_consent_mode_settings": { "ad_personalization": "denied", "ad_storage": "denied", "ad_user_data": "denied", "ads_data_redaction": false, "analytics_storage": "denied", "enable_wait_for_update": false, "functionality_storage": "denied", "personalization_storage": "denied", "security_storage": "denied", "social_storage": "denied", "url_passthrough": false, "wait_for_update": 500 } }, "us": { "enable_banner": true, "enable_decline_button": false, "enable_cookie_preference_button": true, "consent_mode": "opt_out", "enable_consent_by_scroll": true, "enable_google_consent_mode": false, "google_consent_mode_settings": { "ad_personalization": "denied", "ad_storage": "denied", "ad_user_data": "denied", "ads_data_redaction": false, "analytics_storage": "denied", "enable_wait_for_update": false, "functionality_storage": "denied", "personalization_storage": "denied", "security_storage": "denied", "social_storage": "denied", "url_passthrough": false, "wait_for_update": 500 } }, "california": { "enable_banner": true, "enable_decline_button": false, "enable_cookie_preference_button": true, "consent_mode": "opt_out", "enable_consent_by_scroll": true, "enable_google_consent_mode": false, "google_consent_mode_settings": { "ad_personalization": "denied", "ad_storage": "denied", "ad_user_data": "denied", "ads_data_redaction": false, "analytics_storage": "denied", "enable_wait_for_update": false, "functionality_storage": "denied", "personalization_storage": "denied", "security_storage": "denied", "social_storage": "denied", "url_passthrough": false, "wait_for_update": 500 } }, "eu": { "enable_banner": true, "enable_decline_button": false, "enable_cookie_preference_button": true, "consent_mode": "opt_out", "enable_consent_by_scroll": true, "enable_google_consent_mode": false, "google_consent_mode_settings": { "ad_personalization": "denied", "ad_storage": "denied", "ad_user_data": "denied", "ads_data_redaction": false, "analytics_storage": "denied", "enable_wait_for_update": false, "functionality_storage": "denied", "personalization_storage": "denied", "security_storage": "denied", "social_storage": "denied", "url_passthrough": false, "wait_for_update": 500 }, "enable_tcf": false } } } ], "errors": [], "paging": { "next_results": null, "previous_results": null }}
Example 3
Request banners for multiple websites. One website does not exist.
Request
Query
[ { "account_id": "acct_1234", }, { "account_id": "acct_1234", }, { "account_id": "acct_1234", }]
Response
{ "results": [ { "id": "web_1234", "account_id": "acct_1234", "theme_id": "cct_1234", "position": "bottom", "default_theme": "navy_blue", "display_style": "banner", "size": "standard", "personalized_content": true, "running_targeted_advertising": false, "share_data_to_3rd_party": true, "selected_languages": ["en", "pl"], "regions": { "global": { "enable_banner": true, "enable_decline_button": false, "enable_cookie_preference_button": true, "consent_mode": "opt_out", "enable_consent_by_scroll": true, "enable_google_consent_mode": false, "google_consent_mode_settings": { "ad_personalization": "denied", "ad_storage": "denied", "ad_user_data": "denied", "ads_data_redaction": false, "analytics_storage": "denied", "enable_wait_for_update": false, "functionality_storage": "denied", "personalization_storage": "denied", "security_storage": "denied", "social_storage": "denied", "url_passthrough": false, "wait_for_update": 500 } }, "us": { "enable_banner": true, "enable_decline_button": false, "enable_cookie_preference_button": true, "consent_mode": "opt_out", "enable_consent_by_scroll": true, "enable_google_consent_mode": false, "google_consent_mode_settings": { "ad_personalization": "denied", "ad_storage": "denied", "ad_user_data": "denied", "ads_data_redaction": false, "analytics_storage": "denied", "enable_wait_for_update": false, "functionality_storage": "denied", "personalization_storage": "denied", "security_storage": "denied", "social_storage": "denied", "url_passthrough": false, "wait_for_update": 500 } }, "california": { "enable_banner": true, "enable_decline_button": false, "enable_cookie_preference_button": true, "consent_mode": "opt_out", "enable_consent_by_scroll": true, "enable_google_consent_mode": false, "google_consent_mode_settings": { "ad_personalization": "denied", "ad_storage": "denied", "ad_user_data": "denied", "ads_data_redaction": false, "analytics_storage": "denied", "enable_wait_for_update": false, "functionality_storage": "denied", "personalization_storage": "denied", "security_storage": "denied", "social_storage": "denied", "url_passthrough": false, "wait_for_update": 500 } }, "eu": { "enable_banner": true, "enable_decline_button": false, "enable_cookie_preference_button": true, "consent_mode": "opt_out", "enable_consent_by_scroll": true, "enable_google_consent_mode": false, "google_consent_mode_settings": { "ad_personalization": "denied", "ad_storage": "denied", "ad_user_data": "denied", "ads_data_redaction": false, "analytics_storage": "denied", "enable_wait_for_update": false, "functionality_storage": "denied", "personalization_storage": "denied", "security_storage": "denied", "social_storage": "denied", "url_passthrough": false, "wait_for_update": 500 }, "enable_tcf": false } } }, { "id": "web_5678", "account_id": "acct_1234", "theme_id": "cct_5678", "position": "bottom", "default_theme": "navy_blue", "display_style": "banner", "size": "compact", "personalized_content": true, "running_targeted_advertising": false, "share_data_to_3rd_party": true, "selected_languages": ["en", "pl"], "regions": { "global": { "enable_banner": true, "enable_decline_button": false, "enable_cookie_preference_button": true, "consent_mode": "opt_out", "enable_consent_by_scroll": true, "enable_google_consent_mode": false, "google_consent_mode_settings": { "ad_personalization": "denied", "ad_storage": "denied", "ad_user_data": "denied", "ads_data_redaction": false, "analytics_storage": "denied", "enable_wait_for_update": false, "functionality_storage": "denied", "personalization_storage": "denied", "security_storage": "denied", "social_storage": "denied", "url_passthrough": false, "wait_for_update": 500 } }, "us": { "enable_banner": true, "enable_decline_button": false, "enable_cookie_preference_button": true, "consent_mode": "opt_out", "enable_consent_by_scroll": true, "enable_google_consent_mode": false, "google_consent_mode_settings": { "ad_personalization": "denied", "ad_storage": "denied", "ad_user_data": "denied", "ads_data_redaction": false, "analytics_storage": "denied", "enable_wait_for_update": false, "functionality_storage": "denied", "personalization_storage": "denied", "security_storage": "denied", "social_storage": "denied", "url_passthrough": false, "wait_for_update": 500 } }, "california": { "enable_banner": true, "enable_decline_button": false, "enable_cookie_preference_button": true, "consent_mode": "opt_out", "enable_consent_by_scroll": true, "enable_google_consent_mode": false, "google_consent_mode_settings": { "ad_personalization": "denied", "ad_storage": "denied", "ad_user_data": "denied", "ads_data_redaction": false, "analytics_storage": "denied", "enable_wait_for_update": false, "functionality_storage": "denied", "personalization_storage": "denied", "security_storage": "denied", "social_storage": "denied", "url_passthrough": false, "wait_for_update": 500 } }, "eu": { "enable_banner": true, "enable_decline_button": false, "enable_cookie_preference_button": true, "consent_mode": "opt_out", "enable_consent_by_scroll": true, "enable_google_consent_mode": false, "google_consent_mode_settings": { "ad_personalization": "denied", "ad_storage": "denied", "ad_user_data": "denied", "ads_data_redaction": false, "analytics_storage": "denied", "enable_wait_for_update": false, "functionality_storage": "denied", "personalization_storage": "denied", "security_storage": "denied", "social_storage": "denied", "url_passthrough": false, "wait_for_update": 500 }, "enable_tcf": false } } } ], "errors": [ { "account_id": "acct_1234", "error": "object_not_found", "id": "web_2020" } ], "paging": { "next_results": null, "previous_results": null }}