Calls

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

List calls

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 }.

Originate a call

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

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

Node

const res = await fetch("https://api.sautipbx.com/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', … }

Python

import requests

res = requests.post(
    "https://api.sautipbx.com/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', …}

Hang up a call

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=.

Field	Type	Required	Description
sid	string	Required	The call’s sid.

Returns a Call object.

A call can always be cleared

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 reason code END.0504. So a call can always be cleared, never left stuck.

Retrieve a call

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).