If you are looking to manage your Termly account via API or build apps that integrate with Termly, please contact us about becoming an agency partner and making use of our Partner API.
Termly’s Consent API allows you to retrieve the categories and cookies that a given user has consented to.
If you’re setting cookies from the backend, read the guide about how to block cookies using the API.
Authentication
Authentication to the Termly Consent API is done via the API key found on your dashboard. Authentication is unique per website in your account.
GET cookie_whitelist
The cookie_whitelist endpoint returns the consent preferences for a given visitor. this includes a list of every cookie monitored by Termly and the consent category it belongs to.
https://app.termly.io/api/v1/cookie_whitelist
Sample:
curl -H 'Accept: application/json' -H "Authorization: ${API_KEY}"
https://termly.io/api/v1/cookie_whitelist?uuid={UUID}
Request details
Headers
Header | Type | Details |
Authorization (required) | String | Find your API Key from your Termly dashboard |
Query Parameters
Parameter | Type | Details |
uuid (optional) | String | Unique identifier for a visitor who has a consent record. You can get the UUID for a particular visitor from the frontend using the SDK callback. If you do not pass in the UUID, the API will only return the list of cookies classified as Essential. |
API response codes
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." }
API response formats
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 | Type of cookie.
For example: tracker_type, html_local_storage, html_session_storage, server_cookie, pixel_tracker.
The backend may just need to block "server_cookie." |
List response format of categories
Response | Description |
Categories | Whitelisted category name |
Response format of UUID
Response | Description |
uuid | Unique user identity of the data subject (visitor) |