Sonaline

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.

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:

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:

API Token door
Messaging and Callshttps://api.sonaline.com/api/v1/oauth2/token
Partnerhttps://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
400invalidA field is missing or wrong; field names it
401unauthorizedNo credential, or a wrong or expired one
403forbiddenThe account in the path is not the credential's
403scope_missingThe credential lacks the scope the request needs
404not_foundNo such thing on this account
405method_not_allowedThe path does not take that method
409conflictA request with this Idempotency-Key is still running
409idempotency_unresolvedThe first request with this key got no answer; it is not run again
413payload_too_largeThe body is over its size
415invalidThe body is not JSON
422idempotency_mismatchThe Idempotency-Key was used on a different request
429rate_limitedToo many requests, or too many wrong credentials from one address; wait Retry-After seconds
503not_availableThe 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:

Events

Sonaline tells your server what happened in two shapes, kept apart on purpose:

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.