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

getUpdatedCookieWhitelistByTermly(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:


{
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'
}

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' }

GET cookie_whitelist

https://app.termly.io/api/v1/cookie_whitelist

This endpoint allows you to get cookies in the Essential category, or cookies that are consented by a visitor.

Sample Code:


curl -H 'Accept: application/json' -H "Authorization: ${API_KEY}"
https://termly.io/api/v1/cookie_whitelist?uuid={UUID}

Request

Headers

Authorization

REQUIRED

String

Find your API Key from your Termly dashboard

 

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." }

You can get the UUID from the above callbacks using (getUpdatedCookieWhitelistByTermly)

LIST RESPONSE FORMAT OF COOKIES

Response

Description

Name Whitelist cookie name
Provider

Provider domain.

For example: a 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 a subdomain). So you should take into 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