Skip to main content
Welcome to the CookieChimp API. We provide a RESTful API that allows you to access all the data on CookieChimp. You can use our API to integrate your applications, services, and workflows with our platform.

Base URL

All API requests should be made to:

Authentication

To authenticate with the CookieChimp API, you need an API token. Include it in the Authorization header of your HTTP requests as a Bearer token:

Obtaining Your API Token

There are two ways to get an API token:
  1. Via the Dashboard: Go to your API Tokens settings page to create and manage tokens.
  2. Via the API: Use the Login endpoint with your email and password to receive a token.
Both give you a user token: it acts as you, on every account you can access.

Token Types

API tokens can belong to different bearer types:
  • User tokens — Access resources on behalf of a user across their accounts.
  • Partner tokens — Access partner-level resources like groups.
  • Account tokens — Access resources scoped to a specific account. These are not created from the dashboard; contact support if you need one. A user token with account_id covers the same ground.
Most endpoints are scoped to a single account. These accept an account token, or a user token whose user belongs to an account. A partner token does not resolve to one account, so those endpoints reject it with:
The group endpoints work the other way around: they require a partner token and reject user and account tokens with API key must belong to a partner. The account endpoints accept all three.

Rate Limits

To ensure fair usage of the API, we limit the number of requests you can make. The general limit is 300 requests per 5 minutes, counted per API token (or per IP address when no token is sent). A few endpoints have tighter limits, counted per IP address: If you exceed a limit you receive a 429 Too Many Requests response with a Retry-After header giving the number of seconds until the window resets.

Pagination

List endpoints support pagination with the following query parameters. Banner templates is the one exception — it returns the whole catalogue and accepts neither parameter. Paginated responses include a pagination object with prev_url, next_url, count, page, prev, and next fields. count is the total number of records across all pages, not the number of pages. prev and next are null on the first and last page. page must be a positive integer — anything else returns a 400. A per_page outside 1–50 falls back to 20, and requesting a page past the end returns the last page.

Request Bodies

Resource endpoints expect the resource wrapped under its own key rather than at the top level:
The wrapper matches the resource, though not always the path — /services wraps in site_service: Two endpoints take their body unwrapped: Log in, which takes email and password at the top level, and Create consent banner from a template, which takes jurisdiction_id — a selector for which template to build from, not an attribute of the banner it creates.

Choosing an account

An account API key identifies exactly one account, so there is nothing to choose. A user API key can reach several, and the endpoints that declare an account_id query parameter — the account’s API id — let you say which one you mean. Endpoints that don’t declare it act on the account the key resolves to on its own.
When a user key that can reach several accounts sends no account_id, the request falls back to one of those accounts, and which one is not guaranteed — it can change when you gain access to another account. Always pass account_id if your key can reach more than one account.
Where an endpoint accepts it, reads treat it as optional — it just narrows the request — while writes require it whenever the key can reach more than one account: without it the request would act on an account it picked rather than one you named, so it is refused with a 400. Endpoints that don’t accept the parameter are unaffected either way.

Response Envelopes

Group and account listings use the standard list envelope in the first row — only their single-resource responses are unwrapped. Banner templates are a fixed catalogue rather than a collection of the account’s own records, so that endpoint is not paginated and returns no pagination object.

Errors

The API returns standard HTTP status codes. Authentication, pagination and not-found errors return an errors array of objects with code and message:
Validation errors on categories, storage items and account invitations return an errors array of objects with a single human-readable error:
Three endpoints — Create group, Update group and Update account user — render the model’s errors directly instead, as an object keyed by attribute:
Every other validation failure uses the errors array above, including refusing to remove an account owner. Two specific failures return a single top-level error string: rejected credentials on Log in, and a wrong current password or invalid new password on Change password.
This applies only to those two failures. Everything else on those endpoints — a missing or invalid bearer token, or a rate limit — uses the errors array shape above.