Numbers

Acquire numbers from the pool, release them, and point them at a webhook.

GET/numbers/

List numbers you own. Returns array<Number>.

GET/numbers/available

List numbers in the pool you can acquire. Returns array<{ uuid: string, number: string }>.

POST/numbers/acquire

Acquire a pool number. Charges the one-time setup fee to your wallet.

Field	Type	Required	Description
uuid	string	Required	The pool number's `uuid`.

Header Idempotency-Key (optional, recommended — a retry never charges twice). Returns a Number object. Errors 404 unknown, 409 already taken, 402 insufficient funds.

curl https://sauti-pbx.services.co.ke/api/numbers/acquire \
  -H "Authorization: Bearer sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{ "uuid": "the-number-uuid" }'

// → 200 OK
{ "uuid": "...", "number": "+254709080010", "is_active": true, … }

const res = await fetch('https://sauti-pbx.services.co.ke/api/numbers/acquire', {
  method: 'POST',
  headers: { 'Authorization': 'Bearer sk_live_...', 'Content-Type': 'application/json' },
  body: JSON.stringify({ uuid: 'the-number-uuid' }),
});
const number = await res.json();

import requests

res = requests.post(
    'https://sauti-pbx.services.co.ke/api/numbers/acquire',
    headers={'Authorization': 'Bearer sk_live_...'},
    json={'uuid': 'the-number-uuid'},
)
number = res.json()

POST/numbers/release

Return a number to the pool. Body { uuid: string }. Returns { message: string }.

POST/numbers/configure

Update a number's per-purpose webhook URL overrides and/or friendly name. Only provided fields are changed. A blank URL for a purpose clears the per-DID override so that purpose falls back to the account default.

Field	Type	Required	Description
uuid	string	Required	The number to configure.
webhook_urls	object, nullable	Optional	Per-purpose URL overrides — `{ voice_inbound?, voice_outbound?, status? }`. Omit a key to leave that purpose unchanged.
friendly_name	string, nullable	Optional	A label for your own reference.

Returns a Number object.

The Number object

Field	Type	Description
uuid	string	Stable identifier.
number	string	The DID in E.164.
friendly_name	string	Your label.
webhook_urls	object	Per-purpose URL overrides keyed by purpose value (`voice_inbound`, `voice_outbound`, `status`). Empty string = inherits account default for that purpose.
webhook_inbound	object	The resolved inbound route: `{ url, source }` where `source` is `custom` (this number's override), `default` (account default), or `none`. Use this to see where inbound calls actually go.
is_active	boolean	Whether the number is live.
acquired_at	string, nullable	When you acquired it.