Base URL
All API requests should be made to:Authentication
To authenticate with the CookieChimp API, you need an API token. Include it in theAuthorization header of your HTTP requests as a Bearer token:
Obtaining Your API Token
There are two ways to get an API token:- Via the Dashboard: Go to your API Tokens settings page to create and manage tokens.
- Via the API: Use the Login endpoint with your email and password to receive a token.
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_idcovers the same ground.
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:/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 anaccount_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.
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:
errors array of objects with a single human-readable error:
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.
errors array shape above.