Developers
Build on Sonaline
Sonaline's public APIs: text from your own software through the Messaging API, see and act on your calls through the Calls API, make and look after workspaces through the Partner API, and have any phone system report its calls and recordings to a workspace.
Last updated 21 November 2026
Guides
This page is what every API shares; each guide is a chapter of its own. Each API is also described as an OpenAPI 3.1 file, made from its routes: messaging.json, calls.json and partner.json.
- Messaging APISend and receive texts and pictures, list your message history and delivery quality, and take delivery callbacks, over HTTPS and JSON.
- Calls APISee the calls up on your lines and act on them (take over, transfer, park, hold, hang up), place calls from your CRM, follow presence and Do Not Disturb, read the call history and recordings, set lines up, and hear about every call through signed webhooks.
- Partner APIMake your customers' workspaces, change their name and features, and read your bills, from your own systems.
- Phone-system call logReport every call your phone system handles, and upload its recording, so each call is filed under the right person in Sonaline.
Credentials
Every API takes a client id and a client secret, made by a signed-in person and never by an API call. A workspace's credentials belong to the workspace, and a workspace admin makes them in the Admin Center at sonaline.app/manage:
- Messaging API: Advanced, API & webhooks, in the API credentials section. Make API credentials gives a client ID and a client secret, and the page shows your account ID. Add an application under API applications for the callback URL your replies and delivery reports go to.
- Calls API: the same API credentials section. Tick what each credential may do (see calls, move and place calls, presence, recordings, provisioning) when you make it, or later with Scopes. Call webhooks are added in the Call webhooks section beside it; each one's signing secret is shown once.
- Partner API: a partner's own credentials, which a partner Owner makes, signed in, in the Admin center (the Partner chapter, Making a credential).
- Phone-system call log (not an API of this family: a phone system reporting its calls): Phone systems, then the phone system, then Connect under Call log from this phone system. The page shows the two URLs and a token, once (https://sonaline.com/developers/call-log).
A workspace connected through a partner makes its own Messaging API credentials the same way; the partner keeps the API's on/off switch.
The secret is shown once, when the credential is made or rotated; Sonaline keeps only a hash of it. If it is lost, rotate it. Each credential carries scopes, chosen when it is made and changed in the same place. Scopes, revocation and the switches that can stop a request are read on every request, so a change applies at once, to tokens already handed out too.
A workspace's credential does not work on the Partner API, and a partner's
does not work on a workspace's APIs: both answer 401.
Signing in
Sign in either way:
- A token:
POSTto the API's token door withAuthorization: Basic base64(client_id:client_secret)and the form bodygrant_type=client_credentials. The answer'saccess_tokenis good for one hour: send it asAuthorization: Bearer <token>. - Basic on each request:
Authorization: Basic base64(client_id:client_secret).
| API | Token door |
|---|---|
| Messaging and Calls | https://api.sonaline.com/api/v1/oauth2/token |
| Partner | https://api.sonaline.com/api/v1/partners/oauth2/token |
curl -sS -X POST https://api.sonaline.com/api/v1/oauth2/token \
-u "$CLIENT_ID:$CLIENT_SECRET" -d grant_type=client_credentials
{"access_token": "example_token", "token_type": "Bearer", "expires_in": 3600}
The token doors give client-credentials tokens only. Keys go in headers only, never in a URL.
Your account number
Every path names the account it acts on, and a credential works on its own
account only: any other answers 403 forbidden. A workspace's account
id is shown beside its credentials in the Admin Center; a partner's
account number (seven digits) beside the partner's.
https://api.sonaline.com/api/v1/accounts/{accountId}/... Calls API
https://api.sonaline.com/api/v1/partners/{accountId}/... Partner API
The Messaging API keeps Bandwidth's paths (its chapter, section 1).
Errors
The Calls and Partner APIs answer every refusal in one shape:
{ "error": { "code": "invalid", "message": "Field 'to' is required", "status": 400, "field": "to" } }
code is stable: act on it. message is plain words and may change; it
never repeats what you sent. field names the field, for invalid.
The codes every one of them uses:
| Status | Code | Meaning |
|---|---|---|
| 400 | invalid | A field is missing or wrong; field names it |
| 401 | unauthorized | No credential, or a wrong or expired one |
| 403 | forbidden | The account in the path is not the credential's |
| 403 | scope_missing | The credential lacks the scope the request needs |
| 404 | not_found | No such thing on this account |
| 405 | method_not_allowed | The path does not take that method |
| 409 | conflict | A request with this Idempotency-Key is still running |
| 409 | idempotency_unresolved | The first request with this key got no answer; it is not run again |
| 413 | payload_too_large | The body is over its size |
| 415 | invalid | The body is not JSON |
| 422 | idempotency_mismatch | The Idempotency-Key was used on a different request |
| 429 | rate_limited | Too many requests, or too many wrong credentials from one address; wait Retry-After seconds |
| 503 | not_available | The feature is not set up on this service yet |
Each chapter lists its own codes beside these. The Messaging API keeps Bandwidth's error body (its chapter, section 7).
Inputs
A field that is missing or of the wrong type, or past its bounds, answers
400 invalid with field naming it; the message names the rule and never
repeats what you sent. What a route does with a field it does not declare
is said in its chapter. A body is read up to its size (64 KB unless the
chapter says otherwise); past it the answer is 413. No cross-site
(browser) calls are allowed: keep the secret on your server.
Limits
Limits are per workspace (or partner) and kind, per minute, over all its
credentials together; each chapter gives its numbers. Every answer to a
request that was counted says where the window stands: RateLimit-Limit
(the most), RateLimit-Remaining (what is left) and RateLimit-Reset
(seconds until the window resets). Because the window is the workspace's
(or partner's), every credential of it sees the others' use. Over a limit
the answer is 429 with Retry-After. A request refused before it is
counted (no credential, a wrong account, a missing scope) carries none of
these.
Wrong credentials are counted too, per address: past a ceiling of wrong tries
in a minute, that address is answered 429 with Retry-After for the rest of
the window, before anything is looked up. A request that signs in correctly is
never counted. The count is of the caller's address only, so nobody can lock
another caller's credential out. It is a guard on cost, not a lock: it is kept
per server and never refuses when it cannot be checked.
While an address is held, every request from it is answered 429,
one with a right credential too, at any API of the family (the two token
doors still give a token for a right pair). An office or a cloud network
behind one address shares that minute: a caller whose wrong tries come
from a shared address holds up the others there until the window ends.
The limit is counted before the Idempotency-Key is looked at: a repeat
with the same key counts in the window like any request, even when it is
answered with the first answer and nothing is done. Spread retries out
(after Retry-After, or a moment) rather than sending them at once.
Request id
Every answer of every API carries
Sonaline-Request-Id: req_..., made by Sonaline for that request (a value
you send is ignored). Quote it to support: it finds the request's line in
the log. It opens nothing and is not a secret. (The Messaging API's token
door too.)
Retries and idempotency
On the Calls and Partner APIs, any write (POST, PUT, PATCH, DELETE) may
carry Idempotency-Key: <1 to 100 visible characters>. The first answer is
kept for 24 hours and given again, with Idempotent-Replayed: true, to a
repeat of the same request (the same method, path, query and body) with the
same key from the same credential; nothing happens twice. The same key on a
different request answers 422 idempotency_mismatch.
Two requests are "the same" when their bytes are: the body is compared
as the text you sent, so the same fields in another order, or other
spacing, are a different request (422). A request the door refuses
before the route runs (its inputs, 400 invalid; its size, 413; the
rate, 429) is not kept under the key: fix it and send it again with the
same key. A refusal by the route itself (404, 409 and the like) is
kept and given again.
On the Messaging API only a send takes the key (other routes ignore it),
with the same rules in Bandwidth's error body: 422 idempotency-key-mismatch,
409 conflict while the first runs, 409 idempotency-key-unresolved
after an unknown outcome, 400 request-validation for a bad key and 413
request-entity-too-large for a body over 1 MB, keyed or not (its chapter, Sending
safely twice).
A write that sends something out (a message, a call placed or moved, a workspace made)
never frees its key when the outcome is unknown (the service failed or did
not answer): a retry is answered 409 idempotency_unresolved, and nothing
is done again. Check the result, and use a new key to try again.
When to try again:
429: afterRetry-Afterseconds;502or503: after a moment, with the same Idempotency-Key (for a write that sends something out, that retry is answered409idempotency_unresolved, as above);- any other
4xx: not until the request is changed.
Events
Sonaline tells your server what happened in two shapes, kept apart on purpose:
- Signed events (the Calls API's webhooks): a
POSTof{id, type, created_at, account_id, data}withSonaline-Signature,Sonaline-Event-Id,Sonaline-Event-TypeandSonaline-Delivery-Id, retried for about a day, with a delivery log and a test event in the Admin Center. How to check the signature is in the Calls chapter, Webhooks. - Messaging callbacks: Bandwidth's body, checked by the callback's
HTTP Basic credentials (and, when your account has one, the optional
X-Signature-256). They are not signed withSonaline-Signature. The Messaging chapter, section 6.
Partners get signed events of the same shape (a workspace made, paused or given a number, a bill sent), registered through the Partner API's own routes with events:write: the Partner chapter, Events.
Questions
Write to hello@sonaline.com.