Sonaline

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:

It can never:

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-credentialsThe 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 /workspacesworkspaces:readquery limit (1 to 200), after (a workspace id, for the next page)
GET /workspaces/{workspaceId}workspaces:read
POST /workspacesworkspaces:writeworkspace (required, letters and digits), display_name (up to 80)
PATCH /workspaces/{workspaceId}workspaces:writedisplay_name, sms (on or off), calls_enabled, voicemail_enabled, app_enabled (true only: Sonaline turns an inbox off)
GET /workspaces/{workspaceId}/usagebilling:readquery month (2026-11)
GET /billingbilling:readquery month
GET /invoicesbilling:read
GET /webhooksevents:write
POST /webhooksevents:writeurl (required), events (required, a list); no Idempotency-Key
GET /webhooks/{webhookId}events:write
PATCH /webhooks/{webhookId}events:writeurl, events, enabled
DELETE /webhooks/{webhookId}events:write
POST /webhooks/{webhookId}/testevents:write
GET /webhooks/{webhookId}/deliveriesevents:writequery 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

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.createdOne of your workspaces was made (here, in the portal or by Sonaline)workspace (id, display_name)
workspace.pausedSonaline or you suspended oneworkspace, paused_at
number.addedA workspace got one or more numbersworkspace, count
bill.readyYour bill for a month was sentmonth, 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.