Calls

Place outbound calls, hang up live ones, and list or fetch call records.

GET/calls/

List call records for your account, newest first.

Query parameters

Name	Type	Required	Default	Description
direction	string	Optional	—	`inbound`, `outbound`, or `internal` (end-user ↔ end-user, on-net).
status	string	Optional	—	`initiated`, `ringing`, `answered`, `completed`, or `failed`.
search	string	Optional	—	Match against the from / to numbers.
from_dt	string	Optional	—	ISO-8601 lower bound on creation time.
to_dt	string	Optional	—	ISO-8601 upper bound.
limit	integer	Optional	`50`	1–200.
offset	integer	Optional	`0`	Rows to skip.

Returns { calls: array<Call>, total, limit, offset }.

POST/calls/originate

Place an outbound call. We dial to, present from as the caller ID, and on answer fetch call-control verbs from url.

Body

Field	Type	Required	Default	Description
to	string	Required	—	Destination number in E.164, e.g. `+254711111111`.
from	string	Required	—	A DID you own, presented as caller ID.
url	string	Required	—	Your webhook that returns verbs for the answered call.
timeout	integer	Optional	`30`	Seconds to wait for an answer.
customPayload	object	Optional	—	Arbitrary JSON echoed back on the call's events and record.

Header Idempotency-Key: string (optional, recommended — see idempotency). Returns a Call object. Errors 402 insufficient balance, 429 traffic cap (see rate limits).

curl https://sauti-pbx.services.co.ke/api/calls/originate \
  -H "Authorization: Bearer sk_live_..." \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: order-4021" \
  -d '{ "to": "+254711111111", "from": "+254709080010",
       "url": "https://yourapp.com/handle-call" }'

// → 201 Created
{ "uuid": "6f1c8e2a-...", "sid": "call_9Xk2", "status": "initiated", … }

const res = await fetch('https://sauti-pbx.services.co.ke/api/calls/originate', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer sk_live_...',
    'Content-Type': 'application/json',
    'Idempotency-Key': 'order-4021',
  },
  body: JSON.stringify({
    to: '+254711111111',
    from: '+254709080010',
    url: 'https://yourapp.com/handle-call',
  }),
});
const call = await res.json();

// → 201 Created
// { uuid: '6f1c8e2a-...', sid: 'call_9Xk2', status: 'initiated', … }

import requests

res = requests.post(
    'https://sauti-pbx.services.co.ke/api/calls/originate',
    headers={
        'Authorization': 'Bearer sk_live_...',
        'Idempotency-Key': 'order-4021',
    },
    json={
        'to': '+254711111111',
        'from': '+254709080010',
        'url': 'https://yourapp.com/handle-call',
    },
)
call = res.json()

# → 201 Created
# {'uuid': '6f1c8e2a-...', 'sid': 'call_9Xk2', 'status': 'initiated', …}

POST/calls/hangup

End a live call. Idempotent — hanging up an already-ended call returns its record unchanged. Also available as GET /calls/hangup/{sid} or GET /calls/hangup?sid=.

If the call has already ended on the switch but our record still shows it live, this brings the record up to date and returns it terminal with reasonCode END.0504 — so a call can always be cleared, never left stuck.

Field	Type	Required	Description
sid	string	Required	The call's `sid`.

Returns a Call object.

GET/calls/{uuid}

Fetch a single call record by its uuid. Returns a Call object, or 404.

The Call object

Field	Type	Description
uuid	string	Stable identifier.
sid	string	Human-friendly call id, e.g. `call_9Xk2`.
direction	string	`inbound`, `outbound`, or `internal` (end-user ↔ end-user, on-net).
from_number / to_number	string	The two ends of the call.
status	string	`initiated` · `ringing` · `answered` · `completed` · `failed`.
reason_code	string	Terminal outcome code, e.g. `END.0200`. See reason codes.
reason_label	string	Readable label for `reason_code`.
duration_seconds	integer, nullable	Total call length.
talk_seconds	integer, nullable	Connected (billed) time.
cost	string	Charge in KES.
tts_seconds	integer	Seconds of speech synthesised.
customPayload	object, nullable	What you attached at originate.
started_at / answered_at / ended_at / created_at	string, nullable	ISO-8601 timestamps (`created_at` always set).