Using the API

Everything the dashboard does goes through a REST API, and that same API is open to your own software: a CRM that sends appointment reminders, a website that sends a confirmation code, a script that reads the replies. The API runs on your gateway, on your server. Your calls never go through us.

This page is for the developer who connects an application to the gateway. It covers what you need for a first working call and the rules every endpoint follows. The full list of endpoints, with every field, lives in the interactive reference built into your gateway.

Base URL

The API answers under /api/v1 on the address of your gateway:

Requests and responses are JSON (Content-Type: application/json). Dates are in ISO 8601, in UTC (2026-09-21T09:14:02Z). Phone numbers are always in international E.164 format: a +, the country code, then the number, with no spaces (+261341234567).

A request body is capped at 2 MiB, which is far more than any send needs. Beyond that the answer is 413 PAYLOAD_TOO_LARGE.

Authentication: API keys

An application authenticates with an API key, sent in the X-API-KEY header of every call:

curl -H "X-API-KEY: sk_..." https://sms.example.com/api/v1/messages?limit=1

The key always travels in that header, never in the URL: a URL ends up in server logs, in browser history and in shared links, and a key written there should be considered leaked. A key in the query string is simply not read.

Keys are created on the API keys page of the dashboard, by a superadmin. Each key has:

The secret is shown once, when the key is created: the gateway only keeps a fingerprint of it. Creating, rotating and revoking keys is explained in API keys.

The three scopes

The scopes are ordered: send can do everything read can, and admin can do everything.

A few reads also require admin, because they hand over a large amount of data at once or describe the inside of the installation: the bulk exports (/export/..., /contacts/export), backups (/backups/...), the list of dashboard accounts (/users) and the technical log (/logs/technical). Creating, editing or deleting dashboard accounts is refused to every key, even admin: those actions need a person signed in to the dashboard.

Give each application the narrowest scope that does the job. A website that sends confirmation codes needs send, not admin.

The dashboard does not use keys

The dashboard signs in with a session cookie, not with a key. That is why some endpoints you see in the reference (sign-in, password, first account) are of no use to an integration: they belong to the dashboard.

A first call: send an SMS and follow it

1. Send

curl -X POST https://sms.example.com/api/v1/messages \
  -H "X-API-KEY: sk_..." \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: order-10482-confirmation" \
  -d '{"to": "+261341234567", "body": "Your order 10482 is ready."}'

The gateway answers 202 Accepted as soon as the message is queued, before it leaves the phone:

{
  "accepted": [
    {
      "id": "0192f0c1-7a3e-7c55-9d1e-2b8f4a6c1d20",
      "conversationId": "0192f0c1-7a3e-7c55-9d1e-2b8f4a6c1d21",
      "direction": "out",
      "phone": "+261341234567",
      "body": "Your order 10482 is ready.",
      "encoding": "gsm7",
      "segments": 1,
      "status": "queued",
      "attempts": 0,
      "createdAt": "2026-09-21T09:14:02Z"
    }
  ]
}

Options of a send

Every field of the request:

Without deviceId and simSlot, the phone and SIM are chosen by your routing settings (routing mode, prefix rules, SIM quotas): see Routing. The daily quota of each SIM and the retries (Settings > Sending) apply to messages sent through the API exactly as to messages sent from the dashboard. The send window and the night pause do not: they only hold campaigns, so an API send leaves at any hour.

The text options of Settings > General, devices (Strip diacritics, Trim extra whitespace, Uppercase everything) also apply to API sends. They are applied when the message leaves for a phone, with that phone's settings: the answer to this request shows body, encoding and segments as you sent them, and GET /messages/{id} shows them as they were sent once the message has left. See Settings.

The reference also lists templateId and variables on this request. The current version of the gateway does not apply them to a send through the API: send the final text in body. Templates are available from the dashboard and in campaigns.

With shortenLinks, replaying a request with the same Idempotency-Key and the same original body returns the message already queued, even though its stored body now carries short links: no second link and no second message is created.

If one recipient is invalid, or has opted out, the whole request is refused and nothing is queued: you never have to guess which part of a request went through.

2. Follow its status

curl -H "X-API-KEY: sk_..." \
  https://sms.example.com/api/v1/messages/0192f0c1-7a3e-7c55-9d1e-2b8f4a6c1d20

The status field moves through the life of the message:

A queued message that waits for the pace of its SIMs also carries holdReason (sim_cadence: the minimum interval between two SMS per SIM; sim_rate: the per-minute limit) and heldUntil, the time it is tried again. Both are null otherwise. It leaves on its own, without spending an attempt.

delivered depends on the carrier sending a delivery receipt: some do not, and a message may then stay at sent even though it arrived. How the queue, retries and send windows work is explained in Sending messages.

Rather than asking again and again, you can let the gateway call you when the status changes: see Webhooks and the message.sent, message.delivered and message.failed events.

Idempotency: retry without sending twice

A network drops at the wrong moment, your script did not get the answer, and it tries again. Without a precaution, the recipient receives the SMS twice.

To avoid that, add an Idempotency-Key header to POST /messages, with a value you choose and that identifies the operation (between 8 and 128 characters, for example order-10482-confirmation):

• the same key sent again within 24 hours with the same body returns the original answer, without sending anything. That answer carries the Idempotency-Replayed: true header;
• the same key sent with a different body is refused with 409 IDEMPOTENCY_CONFLICT: a key names one operation, not a slot to reuse;
• a request that failed (an error answer) does not use the key up: you can correct it and send it again with the same key.

Keys are tied to the caller: another application that happens to choose the same value never receives your answer. Still, choose values that are unique to your application (a UUID, or your order number prefixed with the application's name), because a value already used for a different message is refused. The header is optional, but any integration that retries on its own should send it.

Pagination

Every list is paginated by cursor, never by page number:

The answer has the list in data, and the cursor of the next page in nextCursor, which is null on the last page:

curl -H "X-API-KEY: sk_..." "https://sms.example.com/api/v1/messages?limit=100&direction=in"

{ "data": [ ... ], "nextCursor": "0192f0c1-6b2d-7a10-8c3e-5d4f3a2b1c09" }

Pass the cursor back as it is, without trying to interpret it. The message history comes newest first. Because the cursor points at the last item you received rather than at a page number, messages that arrive while you page through do not shift the pages: nothing is skipped or read twice.

Limits and their headers

When the key has a calls per minute limit, every answer carries:

Beyond the per-minute limit or the daily quota, the answer is 429 RATE_LIMITED with a Retry-After header, in seconds. Wait that long before trying again: a refused call still counts, so retrying faster does not help. The daily quota is counted per UTC day.

Errors

Every error has the same shape, whatever the endpoint:

{
  "error": {
    "code": "INVALID_PHONE",
    "message": "recipient is not a valid international number",
    "details": { "recipient": "0341234567" },
    "requestId": "req_01J8XK2M9F"
  }
}

The codes you are most likely to meet:

An error message never contains the text of an SMS, a full phone number or a key. The complete list of codes is in the reference, under the ErrorCode schema.

What does not produce an error. A phone that is offline or a SIM that reached its daily quota do not refuse the request: the message is accepted (202) and the problem shows later, in its status. When every usable SIM is out of quota, the message waits as pending_quota_exceeded until the quota frees up. When no phone can take it, the gateway retries according to Settings > Sending (4 attempts by default, with growing delays between them) and marks it failed after the last one. Watch its status, or subscribe to message.failed.

The interactive reference

Every gateway carries the complete reference of its own API, generated from the same contract as the code that answers. It cannot describe an endpoint your version does not have.

These pages are readable without signing in: the contract contains no secret and no data of yours. Running a call from them still needs a valid key, with the same checks as any other call. Nothing is loaded from the internet to display them.

To generate a client, point your usual tool (OpenAPI Generator, openapi-typescript, oapi-codegen and so on) at openapi.json.

Before you install. The same reference is on our website, under API reference at the top of this documentation (/docs/api-reference), with its contract at /docs/openapi.json. It describes the latest published version, and its examples use https://your-gateway.example.com/api/v1 as the base URL: replace it with your gateway's address. Nothing you do on that page reaches a gateway, and it has no "Try it out". Once your gateway runs, trust its own reference: it matches your installed version exactly.

Going further

• API keys: create, restrict, rotate and revoke keys.
• Webhooks: be called when an SMS arrives or a status changes.
• Security: what protects your installation and what you should check.