API Reference

The Cliqtel REST API lets you programmatically search and manage DID numbers, and pull usage records, call detail records, billing and balance data for your own reporting and account-management workflows. All responses are JSON. TLS is required on every request.

Base URL: https://cliqtel.com/api · Authenticate with Authorization: Bearer YOUR_API_KEY · Get your API key →

Authentication

Every request carries a Bearer token in the Authorization header. Create and revoke keys under Portal → API Keys. The full token is shown once at creation — store it securely. Tokens look like 17|aBcD… (an id, a pipe, then the secret); send the whole string.

# Example request — list this month's call records
curl https://cliqtel.com/api/v1/portal/usage/calls \
  -H "Authorization: Bearer 17|aBcD3fGhIjK..." \
  -H "Accept: application/json"

Scopes

Keys are least-privilege. The portal offers two presets — Read-only (every *:read scope, ideal for reporting/BI integrations) and Full access (unrestricted). A key may only call endpoints covered by its scopes; anything else returns 403 insufficient_scope. The live catalog is available at GET /api/v1/portal/api-keys/scopes.

Scope	Grants
account:read	Profile, organization, account settings
numbers:read	List and view your numbers
numbers:write	Configure forwarding/labels, cancel numbers
usage:read	Call detail records, usage summaries, breakdowns, exports
billing:read	Invoices, credit notes, wallet balance & transactions
billing:write	Top up wallet, manage payment methods
sms:read / sms:write	List / send SMS
whatsapp:read / whatsapp:write	List / send WhatsApp, manage templates

Errors & Responses

Successful responses use 2xx with a JSON body. Errors use a conventional HTTP status and a JSON envelope with an error and human-readable message. List endpoints are paginated in Laravel's standard shape (data, current_page, last_page, total).

Status	Meaning
200 / 201	Success
401 unauthenticated	Missing or invalid Bearer token
403 insufficient_scope	Key lacks the scope required by this endpoint
422	Validation error — see `errors` for per-field detail
429	Rate limit exceeded — retry after the window resets

// 403 — the key is read-only but the endpoint needs a write scope
{
  "error": "insufficient_scope",
  "message": "This API key is missing the required scope: sms:write.",
  "required_scope": "sms:write"
}

Rate Limits

Reporting and account endpoints are rate-limited per authenticated user. The messaging endpoints (/v1/sms, /v1/whatsapp) allow up to 60 requests/minute. Exceeding a limit returns 429 with a Retry-After header. Design pollers to back off rather than hammer; for large exports prefer /usage/export over paging /usage/calls.

Search Available Numbers

GET /v1/numbers/search Find available numbers · public

Returns available DID numbers matching the criteria, priced at the live retail rate. This endpoint is public (no auth required).

Parameter	Type	Required	Description
country	string	required	ISO 3166-1 alpha-2 country code (e.g. GB, NL)
type	string	optional	local, toll_free, mobile, or national

// Response
{ "numbers": [ { "number": "+442079460831", "country_code": "GB", "type": "local", "monthly_price": 2.00 } ] }

List & Configure Your Numbers

Manage the numbers on your account. List/view need numbers:read; the mutations need numbers:write.

Method	Path	Description
GET	/v1/portal/numbers	List your numbers
GET	/v1/portal/numbers/{id}	View a single number
PATCH	/v1/portal/numbers/{id}/forwarding	Set forwarding destination
PATCH	/v1/portal/numbers/{id}/label	Rename / label a number
POST	/v1/portal/numbers/{id}/cancel	Cancel a number at period end

Usage Summary

GET /v1/portal/usage/summary KPIs + balances · usage:read

Headline usage and balance figures for a date window (defaults to the current month). Accepts from and to (YYYY-MM-DD).

// Response
{
  "minutes_this_month": 1284.5,
  "charges_this_month": 42.17,
  "total_calls": 318,
  "active_calls": 2,
  "open_holds": 0.40,
  "wallet_balance": 75.60,
  "available_balance": 75.20,
  "billing_mode": "prepaid",
  "credit_limit": 0
}

Call Detail Records

GET /v1/portal/usage/calls Paginated CDRs · usage:read

Itemised, billed call records. Filter with from, to (YYYY-MM-DD), country (dialling code), and per_page. Returns Laravel pagination.

// Response (data[] items)
{
  "id": 90211,
  "call_id": "a1b2c3",
  "destination": "+4915112345678",
  "caller_id": "+442079460831",
  "start_time": "2026-06-01T09:14:22+00:00",
  "duration_seconds": 183,
  "billable_seconds": 183,
  "rate_per_minute": 0.0190,
  "charge": 0.06,
  "currency": "EUR",
  "billing_status": "posted"
}

Usage Breakdowns & Comparison

Pre-aggregated views over the same window, all requiring usage:read:

Path	Returns
/v1/portal/usage/chart	Daily minutes / cost / calls (for trend charts)
/v1/portal/usage/by-did	Per-number minutes, calls, cost
/v1/portal/usage/by-destination	Per destination country
/v1/portal/usage/by-trunk	Per SIP trunk
/v1/portal/usage/comparison	This month vs last month with deltas

Export Usage

GET /v1/portal/usage/export CSV / XLSX / PDF · usage:read

Streams the full call history for the window as a file. Use format = csv (default), xlsx, or pdf, plus from / to. Best path for bulk reporting — one request instead of paging.

Invoices & Credit Notes

All require billing:read.

Path	Returns
/v1/portal/invoices	Invoice history (number, totals, status, has_pdf)
/v1/portal/invoices/{id}/pdf	Invoice PDF
/v1/portal/credit-notes	Credit note history
/v1/portal/billing/timeline	Unified billing event timeline
/v1/portal/orders	Order history

// GET /v1/portal/invoices
{ "invoices": [ {
  "invoice_number": "INV-2026-0042",
  "total": 12.10, "subtotal": 10.00, "tax": 2.10,
  "currency": "EUR", "status": "paid", "has_pdf": true
} ] }

Wallet Balance

GET /v1/wallet/balance Current balance · billing:read

// Response
{ "balance": 75.60, "currency": "EUR" }

Wallet Transactions

GET /v1/wallet/transactions Credit/debit ledger · billing:read

Paginated wallet ledger: top-ups, call/message debits, refunds, each with amount, balance_after, type, and reference_type.

Send SMS

POST /v1/sms/messages Send a message · sms:write

Parameter	Type	Required	Description
from	string	required	One of your SMS-enabled numbers (E.164)
to	string	required	Recipient in E.164
body	string	required	Message text

// 201 Response
{ "data": {
  "id": 5521, "from": "+442079460831", "to": "+4915112345678",
  "status": "queued", "segments": 1, "cost": 0.0400, "currency": "EUR"
} }

List SMS · GET /v1/sms/messages · sms:read

Paginated inbound + outbound SMS history. GET /v1/sms/messages/{id} returns a single message; GET /v1/sms/numbers lists your SMS-capable numbers.

Send WhatsApp message

POST /v1/whatsapp/messages Send a message · whatsapp:write

One endpoint sends every WhatsApp message kind — the type field selects the shape. Templates can start a conversation at any time; free-form messages (text, media, location, interactive) are only allowed inside the 24-hour customer-service window.

Parameter	Type	Required	Description
account_id	integer	required	Your WhatsApp account id (from `GET /v1/whatsapp/accounts`)
to	string	required	Recipient in E.164, e.g. `+31611398058`
type	string	required	One of `template`, `text`, `media`, `location`, `interactive`
template	object	type=template	name, language, components (approved template)
body	string	type=text	Message text, up to 4096 chars
media	object	type=media	type (image/video/document), id, caption, filename
location	object	type=location	latitude, longitude, name, address
interactive	object	type=interactive	Reply buttons (≤3) or a list menu (see below)
status_callback_url	string	optional	URL to receive delivery-status webhooks for this message

// text — inside the 24h window
{ "account_id": 5, "to": "+31611398058", "type": "text",
  "body": "Thanks! Your request is on its way." }

// template — starts a conversation any time
{ "account_id": 5, "to": "+31611398058", "type": "template",
  "template": { "name": "order_update", "language": { "code": "en" },
    "components": [ { "type": "body", "parameters": [ { "type": "text", "text": "10432" } ] } ] } }

// media (image/video/document by uploaded media id)
{ "account_id": 5, "to": "+31611398058", "type": "media",
  "media": { "type": "image", "id": "1234567890", "caption": "Your receipt" } }

// location
{ "account_id": 5, "to": "+31611398058", "type": "location",
  "location": { "latitude": 38.7223, "longitude": -9.1393,
    "name": "Cliqtel Lisbon", "address": "Av. da Liberdade, Lisboa" } }

// interactive — reply buttons (max 3)
{ "account_id": 5, "to": "+31611398058", "type": "interactive",
  "interactive": { "type": "button",
    "body": { "text": "Confirm your appointment for Thursday 10:00?" },
    "action": { "buttons": [
      { "type": "reply", "reply": { "id": "yes", "title": "Yes" } },
      { "type": "reply", "reply": { "id": "no",  "title": "Reschedule" } } ] } } }

// interactive — list menu (max 10 rows)
{ "account_id": 5, "to": "+31611398058", "type": "interactive",
  "interactive": { "type": "list",
    "body": { "text": "How can we help?" },
    "action": { "button": "Choose a topic", "sections": [
      { "title": "Support", "rows": [
        { "id": "billing",   "title": "Billing",   "description": "Invoices & payments" },
        { "id": "technical", "title": "Technical", "description": "Setup & troubleshooting" } ] } ] } } }

// 201 Response
{ "data": {
  "id": 88213, "account_id": 5, "from": "+351300305340", "to": "+31611398058",
  "type": "text", "status": "sent", "cost": 0.0000, "currency": "EUR",
  "created_at": "2026-08-22T12:04:11+00:00"
} }

Status transitions sent → delivered → read (or failed) and are pushed to status_callback_url if set. On an empty wallet the call returns 402 with error.code = insufficient_balance.

List WhatsApp messages · GET /v1/whatsapp/messages · whatsapp:read

Paginated inbound + outbound history. Filter by account_id and status. GET /v1/whatsapp/messages/{id} returns a single message with its current delivery status, cost, and any error.

WhatsApp accounts · GET /v1/whatsapp/accounts · whatsapp:read

Lists your connected WhatsApp accounts with id, display_name, verified_name, status, quality_rating, and messaging_limit. Use the id as account_id when sending.

Templates

GET /v1/whatsapp/templates List approved templates · whatsapp:read

Filter by account_id and status. Create with POST /v1/whatsapp/templates (whatsapp:write) and remove with DELETE /v1/whatsapp/templates/{id}.

Parameter (create)	Type	Required	Description
account_id	integer	required	WhatsApp account id
name	string	required	Lowercase, digits and underscores only (`^[a-z0-9_]+$`)
category	string	required	`AUTHENTICATION`, `UTILITY`, or `MARKETING`
language	string	required	Language code, e.g. `en`
components	array	required	Template components (header/body/buttons) per Meta's format

Contact groups

POST /v1/whatsapp/contact-groups Create a group · whatsapp:write

GET /v1/whatsapp/contact-groups (whatsapp:read) lists your groups. POST /v1/whatsapp/contact-groups/{group}/contacts adds contacts (1–5000 per call); phone numbers are normalised and de-duplicated, and opted-out contacts are skipped at send time.

Parameter	Type	Required	Description
name	string	required	Group name (create), up to 120 chars
contacts[]	array	add contacts	Each item: phone (E.164, required), optional name

// add contacts
{ "contacts": [
  { "phone": "+351300111222", "name": "Ana" },
  { "phone": "+351300333444" }
] }

Broadcasts (campaigns)

POST /v1/whatsapp/broadcasts Create a broadcast · whatsapp:write

Sends an approved template to every sendable contact in a group. Start it with POST /v1/whatsapp/broadcasts/{id}/start; poll GET /v1/whatsapp/broadcasts/{id} for live counters. Sends are throttled to protect your quality rating.

Parameter	Type	Required	Description
account_id	integer	required	WhatsApp account id
contact_group_id	integer	required	Group to send to
name	string	optional	Campaign name, up to 120 chars
template	object	required	name (approved) + language
variables	object	optional	Per-placeholder values; supports `name` personalisation
scheduled_at	string	optional	ISO-8601 time to send later
start	boolean	optional	Start immediately on create

// create + start a campaign
{ "account_id": 5, "contact_group_id": 12, "name": "Spring promo",
  "template": { "name": "spring_sale", "language": "en" },
  "variables": { "1": "{{name}}" }, "start": true }

// GET /v1/whatsapp/broadcasts/{id} — live counters
{ "data": { "id": 31, "status": "sending", "total": 1200,
  "sent": 840, "delivered": 812, "read": 655, "replied": 40,
  "failed": 3, "cost_cents": 6720, "currency": "EUR" } }

Roadmap

The items below are planned, not yet available. They are listed here so you can plan around them — do not build against them yet.

Outbound webhooks — push notifications for number.provisioned, payment.succeeded, etc. Today, poll the reporting endpoints above.
Official SDKs (Node.js, Python) — the API is plain REST + Bearer auth, so any HTTP client works in the meantime.
Number ordering via API — purchase/provisioning is currently completed in the portal checkout.