Quickstart

Go from a new account to a live phone call in five steps. You do not need a server of your own. The platform can host your call logic for you. Bring a server when that logic has to change from one call to the next.

Create an account
Section titled “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.

Already have an account? Head to your dashboard.
Create an API key
Section titled “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.

sk_live_... keys carry the full power of your account. Client-side code should use a short-lived phone token instead.

Send it as a bearer token on every request:
```
Authorization: Bearer sk_live_...
```
Verify it works by fetching your account:
Terminal window
```
curl https://api.sautipbx.com/api/account/ \
  -H "Authorization: Bearer sk_live_..."
```

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://api.sautipbx.com/api/numbers/available \
  -H "Authorization: Bearer sk_live_..."

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

Write your call logic
Section titled “Write your call logic”

When a call comes in, we ask for a <Response> document of verbs. Here is one that greets the caller and hangs up:
```
<Response>
  <Say voice="woman">Karibu SautiPBX.</Say>
  <Hangup/>
</Response>
```
The short way. Let us host it. Open Assets in the portal, choose New document, paste the document above and save it. Choose Copy URL. That URL is your webhook, and there is nothing to deploy or keep running. See Assets.

The other way. Run your own server. Do this when the answer has to change per call, for example routing by caller or looking something up in your database. We POST the call’s details and your server replies with the document:
app.py
```
# 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")
```
Either way, point your number at the URL with POST /numbers/configure, or set an account-wide default under Webhooks in the portal.

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://api.sautipbx.com/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.

Next steps

Core conceptsHow the REST API, webhooks and the event stream fit together.

Call controlEvery verb you can return from your handler.

Quickstart

Create an account

Create an API key

Acquire a phone number

Write your call logic

Place your first call

Next steps