Quickstart: Place a Call
Sautikit quickstart: sign up, top up in KES, claim a Kenyan number for KES 500 a month, set its voice callback and place a call with POST /v1/calls.
Sautikit quickstart: sign up, top up in KES, claim a Kenyan number for KES 500 a month, set its voice callback and place a call with POST /v1/calls.
To place a call with the Sautikit API, create an API key, top up your KES wallet, claim a Kenyan number (KES 500 a month), set its voice callback URL and send POST /v1/calls. Calls to Kenyan numbers are KES 3.00 a minute, billed per second after answer, and incoming calls are free. The five steps below take you from a new account to a live outbound call.
curl and jq, plus Node.js 18+ or Python 3.9+ for the callback server.ngrok http 3000 or cloudflared tunnel gives you one.All API requests go to https://api.sautikit.com.
Sign up at sautikit.com: enter your email address and click the link that arrives in your inbox.
In the console, open API keys and create a key. The key is a long token that starts with eyJ. It is shown once, so store it now:
export SAUTIKIT_API_KEY="eyJhbGciOiJFUzI1NiIs..."Check that the key works:
curl -s "https://api.sautikit.com/v1/wallet/balance" \
-H "Authorization: Bearer $SAUTIKIT_API_KEY" | jq .{
"balance_minor": 0,
"currency": "KES",
"server_time": "2026-06-27T12:00:00Z"
}A new workspace starts at zero.
Sautikit is prepaid in Kenyan shillings. In the console, open Wallet, choose Top up and pay by M-Pesa or card. KES 1,000 covers a number and plenty of test calls.
API amounts are in minor units: 100 is KES 1.00, so 100000 is KES 1,000. Confirm the balance:
curl -s "https://api.sautikit.com/v1/wallet/balance" \
-H "Authorization: Bearer $SAUTIKIT_API_KEY" | jq .balance_minorOutbound calls leave on a number you own. List the numbers available in Kenya:
curl -s "https://api.sautikit.com/v1/numbers/available?country=KE" \
-H "Authorization: Bearer $SAUTIKIT_API_KEY" | jq '.available[0]'{
"inventory_id": "01900000-0000-7000-8000-000000000001",
"e164": "+254720000000",
"country": "KE",
"capabilities": ["voice"],
"monthly_price_minor": 50000,
"currency": "KES",
"inbound_per_min_minor": 0,
"outbound_per_min_minor": 300
}Claim it with its inventory_id:
curl -s -X POST "https://api.sautikit.com/v1/numbers/01900000-0000-7000-8000-000000000001/claim" \
-H "Authorization: Bearer $SAUTIKIT_API_KEY" | jq .{
"number": {
"id": "01900000-0000-7000-8000-000000000002",
"e164": "+254720000000",
"status": "active"
},
"prorated_minor": 6667,
"monthly_minor": 50000,
"currency": "KES",
"next_renewal_at": "2026-07-01T00:00:00Z"
}A number is KES 500 a month with no setup fee. The claim charges the rest of the current month (prorated_minor). Store the number's id and e164:
export NUMBER_ID="01900000-0000-7000-8000-000000000002"
export FROM_NUMBER="+254720000000"When the person you call picks up, Sautikit POSTs a JSON body to your number's voice callback URL and runs the voice actions you reply with. Your server has up to 60 seconds to answer, but the person is already listening, so reply fast.
import express from "express";
const app = express();
app.use(express.json());
// Sautikit POSTs here when the call is answered, and again when it ends.
app.post("/voice", (req, res) => {
if (req.body.callSessionState === "Completed") {
return res.json({ actions: [] });
}
// On an outbound call, clientDialedNumber is the person you called.
console.log("answered by", req.body.clientDialedNumber);
res.json({
actions: [
{ say: { text: "Hello from Sautikit. Your call is connected." } },
{ hangup: {} },
],
});
});
app.listen(3000, () => console.log("Voice server on :3000"));from fastapi import FastAPI, Request
app = FastAPI()
@app.post("/voice")
async def voice(request: Request):
body = await request.json()
if body.get("callSessionState") == "Completed":
return {"actions": []}
return {
"actions": [
{"say": {"text": "Hello from Sautikit. Your call is connected."}},
{"hangup": {}},
]
}Point the number at your server with PUT /v1/numbers/{id}/routing:
curl -s -X PUT "https://api.sautikit.com/v1/numbers/$NUMBER_ID/routing" \
-H "Authorization: Bearer $SAUTIKIT_API_KEY" \
-H "Content-Type: application/json" \
-d '{"voice_callback_url": "https://your-server.example.com/voice"}' | jq .routingReplace +254720000001 with the mobile number you want to ring. to is an array of strings.
const response = await fetch("https://api.sautikit.com/v1/calls", {
method: "POST",
headers: {
Authorization: `Bearer ${process.env.SAUTIKIT_API_KEY}`,
"Content-Type": "application/json",
},
body: JSON.stringify({
from: process.env.FROM_NUMBER,
to: ["+254720000001"],
}),
});
const call = await response.json();
console.log(call.call_id, call.session_id, call.status);curl -s -X POST "https://api.sautikit.com/v1/calls" \
-H "Authorization: Bearer $SAUTIKIT_API_KEY" \
-H "Content-Type: application/json" \
-d "{\"from\": \"$FROM_NUMBER\", \"to\": [\"+254720000001\"]}" | jq .import os
import httpx
resp = httpx.post(
"https://api.sautikit.com/v1/calls",
headers={"Authorization": f"Bearer {os.environ['SAUTIKIT_API_KEY']}"},
json={"from": os.environ["FROM_NUMBER"], "to": ["+254720000001"]},
)
call = resp.json()
print(call.get("call_id"), call["session_id"], call["status"])The API answers 201 as soon as the call starts ringing:
{
"call_id": "01900000-0000-7000-8000-000000000003",
"session_id": "HD_9f2c1a7b",
"status": "ringing"
}Your phone rings. Answer it and you hear the greeting from Step 4.
Fetch the call record:
curl -s "https://api.sautikit.com/v1/calls?limit=1" \
-H "Authorization: Bearer $SAUTIKIT_API_KEY" | jq '.data[0] | {id, status, duration_seconds, cost_minor}'{
"id": "01900000-0000-7000-8000-000000000003",
"status": "completed",
"duration_seconds": 12,
"cost_minor": 60
}The charge is on your wallet statement as a call_debit line:
curl -s "https://api.sautikit.com/v1/wallet/statements?kind=call_debit&limit=5" \
-H "Authorization: Bearer $SAUTIKIT_API_KEY" | jq .dataCalls to Kenyan numbers are KES 3.00 a minute, billed per second after the call is answered. Incoming calls are free. Unanswered calls cost nothing.
| Answered call | Cost |
|---|---|
| 12 seconds | KES 0.60 (60 minor units) |
| 25 seconds | KES 1.25 (125 minor units) |
| 90 seconds | KES 4.50 (450 minor units) |
The rates for a number are in inbound_per_min_minor and outbound_per_min_minor on the number search in Step 3.
Check that the header reads Authorization: Bearer <key> and that the key was not cut short when you copied it.
The wallet is at zero or below. Top up by M-Pesa or card, then retry. Claiming a number charges the wallet too, so keep enough for the number and your calls.
from is not an active number in this workspace. Use the e164 value from Step 3.
A number in to is not valid. Use the international format, for example +254720000001.
Your voice callback did not return valid voice actions. Check that the URL in the number's routing is public and HTTPS, that it answers POST with a 2xx, and that the body is {"actions": [...]}.
Fetch the call with GET /v1/calls/{call_id} and read status and failure_code. no_answer and busy mean the far end did not pick up.