Phone Numbers
How Sautikit numbers work: browse inventory, claim, configure SIP credentials, set routing, and release.
A phone number in Sautikit is a Kenya (+254) DID that moves through a defined lifecycle: available in inventory → claimed to a workspace → active with SIP credentials → optionally released. Each active number carries its own routing configuration that tells the platform where to deliver inbound call events.
Search the inventory before claiming. Filter by country (Kenya = KE) and capability (e.g. voice).
curl -X GET "https://api.sautikit.com/v1/numbers/available?country=KE¤cy=KES" \
-H "Authorization: Bearer $SAUTIKIT_API_KEY"Response includes monthly_price_minor (KES, in minor units; divide by 100 for shillings), inbound_per_min_minor, and outbound_per_min_minor.
Claiming atomically charges the first month's rental from your KES wallet and creates a tenant_number record.
curl -X POST "https://api.sautikit.com/v1/numbers/01900000-0000-7000-8000-000000000001/claim" \
-H "Authorization: Bearer $SAUTIKIT_API_KEY"If your wallet balance is insufficient the API returns 402 wallet_insufficient_funds. Top up via M-Pesa STK push before retrying.
| State | Meaning |
|---|---|
available | In the public inventory pool; claimable |
reserved | Held for a few seconds during a claim transaction |
assigned | Owned by a workspace; billing is active |
released | Returned to the pool; billing stops immediately |
A tenant_number record separately tracks:
| Status | Meaning |
|---|---|
active | Normal, in use |
suspended | Temporarily suspended (admin action) |
released | Deactivated; number returned to inventory |
Once claimed, create SIP credentials so a soft-phone or PBX can register the number.
curl -X POST "https://api.sautikit.com/v1/numbers/{id}/sip-credentials" \
-H "Authorization: Bearer $SAUTIKIT_API_KEY" \
-H "Content-Type: application/json" \
-d '{"label": "main-ivr"}'The response returns username and password once only. Store the password immediately; only an Argon2id hash is retained server-side. If you lose the password, rotate via POST /v1/numbers/{id}/sip-credentials/{cred_id}/rotate.
Credential statuses:
| Status | Meaning |
|---|---|
active | Valid for SIP registration |
revoked | Permanently disabled; create a new credential |
Routing tells Sautikit where to POST inbound call events (voice actions) and call lifecycle events.
curl -X PATCH "https://api.sautikit.com/v1/numbers/{id}/routing" \
-H "Authorization: Bearer $SAUTIKIT_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"voice_callback_url": "https://ivr.example.com/voice",
"events_url": "https://ivr.example.com/events"
}'voice_callback_url: Sautikit POSTs here on each call step. Your server returns a VoiceAction DSL response.events_url: Sautikit POSTs call lifecycle events (call.started, call.answered, call.completed, call.failed, call.recording.ready). These are per-number, not workspace webhooks.Both URLs must be https:// in production. The platform rejects plain http:// endpoints.
Rental is charged on the first day of each calendar month from your KES prepaid wallet. The charge is recorded as a number_rental ledger entry. If the wallet is empty at renewal time the number is suspended until you top up.
Trial numbers provisioned by Sautikit support have a trial_until timestamp. When that timestamp passes the number is automatically released and a reminder email is sent 24 hours before expiry.
curl -X DELETE "https://api.sautikit.com/v1/numbers/{id}" \
-H "Authorization: Bearer $SAUTIKIT_API_KEY"Billing stops immediately on release. The number re-enters the inventory pool and may be claimed by another workspace.