Skip to main content
The Cliqo API v1 lets your systems create and update contacts, read your lists and read campaign metrics. It is intentionally small and stable — every endpoint documented here exists and is measured against production code.

​
Base URL

​
Authentication

Create an API key in Settings › API (Owner or Admin only). The key is shown once, at creation — store it in your secret manager. Send it on every request:
Keys have one of three scopes, chosen at creation: Revoking a key (Settings › API) is immediate and permanent.

​
Brands

A key belongs to the account, and every request operates on the brand bound to that key — the caller cannot select a brand per request, by design (a partner system never chooses where it writes). To integrate with a second brand, create a separate key under that brand in Settings › API.

​
Error format

Errors return a stable machine-readable code — program against code, never against the human-readable message:
Common codes: API_KEY_INVALID (401), API_KEY_REVOKED (401), API_KEY_SCOPE_INSUFICIENTE (403), RATE_LIMITED (429, includes a Retry-After header in seconds), EMAIL_INVALID (400), CONTACT_SUPPRESSED (409), DATE_RANGE_TOO_WIDE (400), METHOD_NOT_ALLOWED (405). Server-side failures use 5xx codes such as REPORT_READ_FAILED (503) — retry with backoff.

​
Rate limits

  • 600 successful calls per key per minute — beyond that, RATE_LIMITED with Retry-After.
  • 10 failed authentication attempts per IP per 10 minutes — beyond that, API_KEY_RATE_LIMITED.

​
Honest-by-design responses

Two conventions worth knowing before you integrate:
  • Metrics that don’t exist come as null, never 0. WhatsApp has no open tracking, so opens is null for WhatsApp campaigns — 0 would be a lie.
  • clicks counts human clicks only (bots, scanners and prefetchers removed). The raw number is available separately as clicks_including_bots.

​
What the API does not have (yet)

We list this rather than let you find out by trying:
  • Campaigns — creating, sending, retrieving or cancelling. Campaigns are built and sent in the app; through the API you read the outcome, at GET /v1/reports/campaigns.
  • Lists — creating or deleting them, and adding or removing a contact from one. Lists are managed in the app; through the API you read them.
  • Deleting a contact, and unsubscribing one. opt_in: false is “I am not declaring consent”, not “unsubscribe this person” — it grants nothing and revokes nothing (criar-contato.js). Someone unsubscribes through the unsubscribe link in the message, or an operator does it in the app; a partner system cannot unsubscribe on their behalf through the API.
  • Segments, templates, WhatsApp.
  • Outbound webhooks and official SDKs — integrations poll the reports endpoint.
When one of these exists, it appears in the reference. If you need one, say so: what we build next comes from real requests — [email protected].

​
Next