Numbers

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

List your numbers

GET /numbers/

List numbers you own. Returns array<Number>.

List available numbers

GET /numbers/available

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

Acquire a number

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

curl https://api.sautipbx.com/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, … }

Node

const res = await fetch("https://api.sautipbx.com/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();

Python

import requests

res = requests.post(
    "https://api.sautipbx.com/api/numbers/acquire",
    headers={"Authorization": "Bearer sk_live_..."},
    json={"uuid": "the-number-uuid"},
)
number = res.json()

Release a number

POST /numbers/release

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

Configure a number

POST /numbers/configure

Update a number’s per-purpose webhook URL overrides and/or friendly name. Only provided fields are changed.

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 it alone.
friendly_name	string, nullable	Optional	A label for your own reference.

Note

A blank URL for a purpose clears the per-DID override, so that purpose falls back to the account default. Omitting the key leaves it unchanged. The two are different.

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 overrides keyed by purpose (voice_inbound, voice_outbound, status). Empty string = inherits the account default.
webhook_inbound	object	The resolved inbound route: { url, source } where source is custom, 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.