Developers · Partner API
Make and look after your customers' workspaces from your own systems
Last updated 20 November 2026
A partner (a reseller, or another system that sets up workspaces on Sonaline) uses its API credentials to make and manage its own workspaces from its own systems, and to read its bills. JSON in, JSON out.
A chapter of the developer guide: signing in, the account in the path, the error shape, limits, the request id, idempotency and events are said there once, for every API. The OpenAPI file: partner.json.
What a credential can and cannot do
A partner credential works from the outside only.
It can:
- read your workspaces (
workspaces:read); - make a workspace, and change its name and its features
(
workspaces:write); - read your bills, invoices and one workspace's usage (
billing:read); - register the endpoints that hear your events, test them and read their delivery log (
events:write).
It can never:
- delete a workspace, suspend or reactivate one, or move money;
- read or send a workspace's messages or calls, see its people, numbers, webhook or settings beyond its name and features;
- act as a workspace's own credential, or make, read or change any credential (yours or a workspace's): that is a signed-in Owner's, in the Admin center.
Each credential carries the scopes you gave it when it was made. More scopes may be added later; the list above is what exists today.
Making a credential
Only a partner Owner, signed in, and only after typing their password (and their authenticator code, where two-factor is on) again. An API call never makes or changes a credential. The client secret is shown once, when the credential is made or rotated; Sonaline keeps only a hash of it. Rotating, changing the scopes or revoking one takes effect at once, and ends its live tokens. A partner holds at most 20 credentials at once. Switching the partner off refuses every credential on its next request.
The portal's routes (https://sonaline.app, with your partner session):
| Method and path | What it does |
|---|---|
GET /partner/api/api-credentials | The list (no secrets), your account number, the scopes available |
POST /partner/api/api-credentials | {label, scopes, password, code?}: a new pair, shown once |
POST /partner/api/api-credentials/<client_id>/rotate | {password, code?}: a new secret, shown once |
PATCH /partner/api/api-credentials/<client_id> | {scopes, password, code?} |
DELETE /partner/api/api-credentials/<client_id> | {password, code?}: revoked at once |
Signing in
Your account number (seven digits) is in every path. Sign in as the
guide says (the guide, Signing in), at the Partner API's own token door,
https://api.sonaline.com/api/v1/partners/oauth2/token:
curl -sS -X POST https://api.sonaline.com/api/v1/partners/oauth2/token \
-u "$CLIENT_ID:$CLIENT_SECRET" -d grant_type=client_credentials
{"access_token": "slp_example", "token_type": "Bearer", "expires_in": 3600}
Routes
Every path below follows https://api.sonaline.com/api/v1/partners/{accountId}.
This table is checked against the OpenAPI file in CI.
| Method and path | Scope | Inputs |
|---|---|---|
GET /workspaces | workspaces:read | query limit (1 to 200), after (a workspace id, for the next page) |
GET /workspaces/{workspaceId} | workspaces:read | |
POST /workspaces | workspaces:write | workspace (required, letters and digits), display_name (up to 80) |
PATCH /workspaces/{workspaceId} | workspaces:write | display_name, sms (on or off), calls_enabled, voicemail_enabled, app_enabled (true only: Sonaline turns an inbox off) |
GET /workspaces/{workspaceId}/usage | billing:read | query month (2026-11) |
GET /billing | billing:read | query month |
GET /invoices | billing:read | |
GET /webhooks | events:write | |
POST /webhooks | events:write | url (required), events (required, a list); no Idempotency-Key |
GET /webhooks/{webhookId} | events:write | |
PATCH /webhooks/{webhookId} | events:write | url, events, enabled |
DELETE /webhooks/{webhookId} | events:write | |
POST /webhooks/{webhookId}/test | events:write | |
GET /webhooks/{webhookId}/deliveries | events:write | query limit (1 to 100) |
A field that is not listed is refused (400 invalid, with field). A
workspaceId is the workspace's full name, such as acme_plumbing. A workspace of
another partner, one of Sonaline's own and one that does not exist all
answer the same 404 not_found.
A new workspace is named <partner>_<workspace>, starts on your default
prices, and is a full workspace with its inbox on; its first admin is
added on its People page. It does hold a key of the old key-style API,
but only as the secret its media addresses are signed with: that key
opens nothing while the workspace's API is switched off (as it is on a
new workspace), and nothing at all once the old API is retired.
Your limits apply, the same as in the partner portal: how many
workspaces you may hold (409 tenant_limit_reached, or tenant_creation_off
until Sonaline sets one) and 20 new workspaces in any 24 hours
(429 daily_tenant_limit). A name that is taken answers 409 name_taken.
Retries and limits
- Making a workspace never frees its Idempotency-Key when the outcome is
unknown: a retry gets the first answer or
409 idempotency_unresolved, never a second workspace (the guide, Retries and idempotency). - Limits are per partner and kind, over all its credentials together: 120 a minute for reads and 30 for writes. The headers are as in the guide (the guide, Limits).
- A body is at most 64 KB.
Errors
Beside the codes every API shares (the guide, Errors), the Partner API
answers 409 name_taken, 409 tenant_limit_reached, 409 tenant_creation_off,
429 daily_tenant_limit, 409 suspended (on a suspended workspace, a change that names
calls_enabled, on or off; Sonaline reactivates it. Its name, sms,
voicemail_enabled and app_enabled are still taken while it is
suspended, but nothing is sent and no call is made or taken through it
until it is reactivated, whatever they say; what it receives is kept) and 409 limit_reached (at most five webhooks).
Events
Your systems can hear when one of your workspaces is made, paused or gets a number, and when your bill is sent. Add up to five HTTPS endpoints with a credential that has events:write (the routes above), and pick the events each one hears:
| Event | When | data |
|---|---|---|
workspace.created | One of your workspaces was made (here, in the portal or by Sonaline) | workspace (id, display_name) |
workspace.paused | Sonaline or you suspended one | workspace, paused_at |
number.added | A workspace got one or more numbers | workspace, count |
bill.ready | Your bill for a month was sent | month, status (sent) |
You hear only of your own workspaces, never another partner's or Sonaline's own. An event holds ids, names and states only: never a key, a secret, a message, a person or a phone number's digits. The workspace is not told.
A delivery is signed and retried as the Calls API's webhooks are (the developer guide, Events): Sonaline-Signature, Sonaline-Event-Id (the same on every try), Sonaline-Event-Type and Sonaline-Delivery-Id; answer a 2xx within 10 seconds, or it is tried again for about a day. Deliveries leave once a minute. The signing secret is shown once, in the answer that made the webhook, so POST /webhooks takes no Idempotency-Key. An endpoint is https on a public host name, never an IP address, a local name or one of Sonaline's own, checked when saved and before every delivery; a redirect is never followed. The delivery log keeps every try for 30 days, with the first 200 characters of a failed answer, never the secret.
The old partner key
The x-partner-key API (/partner/tenants) is retired by a platform
switch; with it on, every path there answers 410. Make API credentials
instead.
Questions
Building an integration and need something the API does not do yet? Write to hello@sonaline.com.