Getting started

Quickstart

Go from a new account to a live phone call in four steps. You will need a server that can receive an HTTP request — that is where your call logic lives.

1. Create an account

Sign up and verify your email. You will receive a temporary password and be guided through setting a permanent one. Then top up your KES wallet so you can acquire a number and place calls.

2. Create an API key

In the portal, open API Keys and create one. The secret is shown once — copy it and store it on your server. Never put it in client-side code.

Send it as a bearer token on every request:

Authorization: Bearer sk_live_...

Verify it works by fetching your account:

curl https://sauti-pbx.services.co.ke/api/account/ \
  -H "Authorization: Bearer sk_live_..."

3. Acquire a phone number

List the pool, pick a number, and acquire it. Acquiring charges a one-time setup fee to your wallet.

# see what's available
curl https://sauti-pbx.services.co.ke/api/numbers/available \
  -H "Authorization: Bearer sk_live_..."

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

4. Host a call handler

When a call comes in, we POST the call's details to your webhook. Reply with a <Response> document of verbs. Here is a handler that greets the caller and hangs up:

# Flask example — return XML, not JSON
from flask import Flask, Response
app = Flask(__name__)

@app.route("/handle-call", methods=["POST"])
def handle_call():
    xml = """<Response>
      <Say voice="woman">Karibu SautiPBX.</Say>
      <Hangup/>
    </Response>"""
    return Response(xml, mimetype="application/xml")

Point your number at this URL with POST /numbers/configure, or set an account-wide default under Webhooks in the portal.

5. Place your first call

Originate an outbound call. We dial to, present your number as from, and hand the answered call to your handler url.

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

The response is the call record, including its sid and status. Watch it progress live on the event stream.