API documentation

If your website is setting cookies from the backend, you will not have access to the JS Callback and will need to use this API to retrieve the cookie whitelist your visitor has consented to

JS Callback

Note: Our consent banner code snippet will automatically handle cookie blocking for your website. You don’t need to implement these callback functions unless you want to add more controlled flows based on your business needs. You will have access to the visitor UUID, as well as the accepted list of cookies, via these callback functions.

getCookieWhitelistByTermly(data)

When is this called?

  • This callback method is triggered automatically each time your visitor refreshes the web page or has navigated to another page on your website (Unless it’s a SPA).

What should I do here

  • Save/Update the whitelist (data.cookieWhiteList) in your front end code if you need to refer to it elsewhere. (e.g.: To set cookie from your frontend code based on what’s in the whitelist.)

Whitelist format
{ cookie_whitelist:
[{ 'name': 'cookiename1', 'provider': 'cookie provider domain1', 'type': 'http_cookie' },
{ 'name': 'cookiename2', 'provider': 'cookie provider domain2', 'type': 'http_cookie' }] }
  • If your website visitor has not yet given consent, you will not be able to get the UUID (data.UUID) here. However, if an UUID is present (i.e.: not null), this means your website visitor has already given consent. You may wish to store the UUID for later use (e.g.: For calling the Termly RESTful API).

    • UUID format

UUID sample
{
uuid: '104697b6-5b10-4aa3-8f8e-52ac2af5ef37'
}

getUpdateCookieWhitelistByTermly(data)

When is this called?

  • This callback method is triggered when your visitor gives consent to the use of cookies via the consent banner or through the cookie preference center installed on your website.

What should I do here?

  • Save the whitelist (data.cookieWhitelist) in your front end code if need to refer to it elsewhere. (e.g.:you need to set cookie from your frontend code based on what’s in the whitelist.)

whitelist format
{ cookie_whitelist:
[{ 'name': 'cookiename1', 'provider': 'cookie provider domain1', 'type': 'http_cookie' },
{ 'name': 'cookiename2', 'provider': 'cookie provider domain2', 'type': 'http_cookie' }] }
  • You will get the UUID (data.UUID) here. You may wish to store the UUID for later use (e.g.: For calling the Termly RESTful API).

UUID format
{
uuid: '104697b6-5b10-4aa3-8f8e-52ac2af5ef37'
}
https://app.termly.io/api/v1/cookie_whitelist
This endpoint allows you to get the Essential Cookies or allowed cookie whitelist of visitor
Request
Response
Headers
Authorization
required
string
You can get your API key from Termly app
Query Parameters
uuid
optional
string
You can get the UUID from the Frontend using the SDK callbacks. If you do not pass in the UUID, the API will only return the list of cookies in the Essential category.
200: OK
API successfully retrieved.
{
cookies:
[
{ 'name': 'cookie_name', 'provider': 'termly.io', 'type': 'http_cookie' },
{ 'name': 'cookie_name', 'provider': 'termly.io', 'type': 'http_cookie' }
]
categories: ['essential'],
uuid: 'xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx'
}
400: Bad Request
{
"error" : "Bad Request"
}
401: Unauthorized
{
"error" : "Access denied!. Invalid token supplied."
}
or
{
"error" : "Access denied!. Deprecated token supplied."
}

Note: You can get the UUID from the Frontend using the JS callbacks.

LIST RESPONSE FORMAT OF COOKIES

Response

Description

name

whitelist cookie name

provider

Provider domain. For example: website with 'https://example.io' may have provider '.example.io' or 'example.io' ('.' in front of example.io means you can use the cookie in subdomain). So you should take account the two possible providers.

type

E.g. tracker_type, html_local_storage, html_session_storage, server_cookie, pixel_tracker Back-end may just need blocking 'server_cookie'.

LIST RESPONSE FORMAT OF CATEGORIES

Response

Description

categories

whitelist category name

RESPONSE FORMAT OF UUID

Response

Description

 uuid

unique user identity of termly