Voice calls & voice OTP
Place outbound calls from your Sozuri voice number, read a one-time code to someone over the phone, and look up every call with its status, duration and price. Same API key and project name as SMS.
- Before you start
- Place a call
- Read a one-time code (voice OTP)
- Look up a call
- Hang up a call
- List recent calls
- List your voice numbers
- Call limits and the status webhook
- Call statuses
- Billing
- Error responses
Before you start
- Your project needs an active voice number. Request one in the dashboard under Project → Voice → Numbers; calls go out from that number, and it is the number your customers see.
-
What a call does once it is answered is set on the number, under When someone calls this
number: play a message, run a call flow (an IVR you build under Voice → Call flows),
send the caller to your call centre, forward to up to five phones (they all ring) or to your own phone system by
its SIP address (
sip:reception@pbx.example.com), or send it to your own URL (ask support for the format your server answers with). An outbound call placed through this API is handled the same way when the person picks up, unless the request carries amessage(read out instead) or aconnect(they are connected to another phone). A voice OTP call only reads the code. -
Authenticate exactly as for SMS: your API key as
Authorization: Bearer <key>(or anapiKeyfield in the query string or body) plusproject, your project's name. See Authentication. -
Unlike the SMS API, every voice error comes back with a 4xx status and a machine-readable
code, so branch on the HTTP status:201means at least one call was placed.
Place a call
| Field | Required | Type | Description |
|---|---|---|---|
| project | Yes | String | Your project's name. |
| to | Yes | String or array | Who to call, in international format (254700000000). Several numbers as an array or a comma-separated string; at most 100 per request. Each number is its own call. |
| from | No | String | Which of your active voice numbers to call from. Leave it out to use your project's first active number. |
| tag | No | String | Up to 60 characters to group these calls by, e.g. reminder. Letters, digits, _ and - are kept (the first 40); filter on it later with List recent calls. |
| message | No | String | Up to 500 characters read out to whoever answers, after which the call hangs up. Leave it out and the call does what your number is set to do. A message call is never recorded. |
| voice | No | String | The voice that reads message: e.g. en-US-Standard-C (English, female), en-US-Standard-B (English, male), en-GB-Standard-A, or sw-KE-Standard-A (Swahili). Leave it out for the default English voice. |
| requestId | No | String | Your own id for this request, up to 64 letters, digits, . _ : -. Send the same requestId again (a retry after a timeout) and you get back the calls the first request placed, with "duplicate": true and 200, and nobody is called twice. One id per thing you want called, e.g. meeting-8812:5m. |
| connect | No | String | Click-to-call: when the person in to answers, they hear message (if you sent one) and are connected to this number, up to five comma-separated numbers (they all ring; the first to answer takes the call), or one SIP address. With an allow-list set, every number here must be on it too, and a SIP address is refused. The connected conversation is recorded when your project records every call. |
curl -X POST https://sozuri.net/api/v1/voice/calls \
-H "Authorization: Bearer $SOZURI_API_KEY" \
-H "Content-Type: application/json" \
-H "Accept: application/json" \
-d '{ "project": "your_project_name", "to": "254700000000", "tag": "reminder",
"message": "Your meeting with the finance team starts in 5 minutes.",
"requestId": "meeting-8812:5m" }'
201 Created, one entry per call placed:
{
"status": "ok",
"requestId": "meeting-8812:5m",
"from": "+254711000000",
"testMode": false,
"calls": [
{ "callSid": "9b2f1c3e-0d4a-4e8b-9a51-6f0c2d7e8a10", "to": "254700000000", "status": "queued", "tag": "reminder_3f9a0c1b2d4e_1" }
]
}
callSidis the call's id: keep it to look the call up.tagis your tag plus a code for this request and the call's position in it, so every call can be told apart.-
Sozuri never calls again on its own. A call nobody answers ends as
no_answer; whether to try again is your decision, and a new attempt needs a newrequestId. -
Each number is dialled separately, so some can be refused while others ring. When that happens the answer is
still
201and carriesrejected, one entry per number that was not called:{ "to": "...", "code": "...", "message": "..." }. When no number could be called the answer is an error with the first refusal'scodeandmessage(see Error responses); a refusal of one of your numbers by your project's call limits also lists them inrejected. testModeistrueonly when the call was simulated and nobody's phone rang. It isfalseon a live project.
Read a one-time code (voice OTP)
Calls one number and reads the code one digit at a time, then repeats it: "Your Acme verification code is 4, 8, 2, 1. Again, 4, 8, 2, 1. Goodbye." The call is never recorded, and the code is not stored, logged or returned.
To try WhatsApp or SMS first and call only when the code did not arrive, send it to
POST /api/v1/otp with "voice" last in
channels: the same call, in the same words, placed only when it is needed.
| Field | Required | Type | Description |
|---|---|---|---|
| project | Yes | String | Your project's name. |
| to | Yes | String | The one number to call, international format. Up to 32 characters. |
| code | Yes | String | The code to read, up to 12 characters. Only its digits are read; anything else is dropped. A code with no digits is refused (invalid_code). |
| brand | No | String | The name read before the code, up to 60 characters. Default Sozuri. |
| repeat | No | Integer | How many times the code is read, 1 to 3. Default 2. |
| voice | No | String | A text-to-speech voice: en-US-Standard-C (the default, female), en-US-Standard-B (male), en-GB-Standard-A, en-GB-Standard-B. A value we don't recognise uses the default. |
| from | No | String | Which of your active voice numbers to call from. Default: your project's first active number. |
curl -X POST https://sozuri.net/api/v1/voice/otp \
-H "Authorization: Bearer $SOZURI_API_KEY" \
-H "Content-Type: application/json" \
-H "Accept: application/json" \
-d '{ "project": "your_project_name", "to": "254700000000", "code": "4821", "brand": "Acme" }'
201 Created:
{
"status": "ok",
"callSid": "5d1e9f07-3a2b-4c6d-8e90-1f2a3b4c5d6e",
"to": "254700000000",
"from": "+254711000000",
"testMode": false
}
Look up a call
One call of your project, with its timeline. A callSid that is not your project's answers 404 not_found.
curl "https://sozuri.net/api/v1/voice/calls/9b2f1c3e-0d4a-4e8b-9a51-6f0c2d7e8a10?project=your_project_name" \
-H "Authorization: Bearer $SOZURI_API_KEY" -H "Accept: application/json"
{
"status": "ok",
"call": {
"callSid": "9b2f1c3e-0d4a-4e8b-9a51-6f0c2d7e8a10",
"direction": "outbound",
"from": "+254711000000",
"to": "254700000000",
"status": "completed",
"statusLabel": "Completed",
"durationSecs": 221,
"billableSecs": 240,
"price": 16.0,
"currency": "KES",
"tag": "reminder_3f9a0c1b2d4e_1",
"requestId": "meeting-8812:5m",
"recordingUrl": null,
"createdAt": "2026-11-08T09:15:02+03:00",
"endedAt": "2026-11-08T09:18:51+03:00",
"events": [
{ "sequence": 1, "event": "start", "occurredAt": "2026-11-08T09:15:09+03:00" },
{ "sequence": 2, "event": "status", "occurredAt": "2026-11-08T09:18:51+03:00" },
{ "sequence": 3, "event": "billed", "occurredAt": "2026-11-08T09:18:51+03:00" }
],
"answers": [
{ "step": "lang", "question": "For English press 1, kwa Kiswahili bonyeza 2.", "digits": "2",
"answer": "Kiswahili", "outcome": "matched", "answeredAt": "2026-11-08T09:15:14+03:00" }
]
}
}
| Field | Description |
|---|---|
| direction | outbound (you placed it) or inbound (someone called your number). |
| status / statusLabel | The call's state and its label: see Call statuses. |
| durationSecs | How long the call lasted once answered. null until it ends. |
| billableSecs, price, currency | What the call was charged, set when it ends (see Billing). null while it is in progress. |
| requestId | The requestId the call was placed with, or null. |
| recordingUrl | Where to download the recording, on Sozuri: https://sozuri.net/api/v1/voice/calls/{callSid}/recording, fetched with your API key and project like any other call. null when there is no recording. Voice OTP calls and calls with a message are never recorded. |
| events | The call's timeline, oldest first: e.g. start (answered), dtmf (a key pressed), flow (call-flow steps run), record, enqueue / dequeue (call centre), status (the final report) and billed. Only on this endpoint, not in the list. |
| answers | Every key the caller pressed at a call flow's menu, oldest first: the menu step, the question as it was asked, the digits, what that key means in your flow (answer, from the meaning you gave the key in the builder, or null), and outcome: matched, invalid (a key the menu does not offer) or no_input (nothing pressed, where the number's provider reports it). Only on this endpoint. Every answer to a flow is also on Voice → Call flows → Answers, counted per question, with a CSV export. |
On a project that records and transcribes every call, the call also carries transcript:
{ "status": "done", "language": "english", "text": "…" }, or null when it was not transcribed.
status is done, failed or too_large (a recording over 25 MB).
Get a call transcript
The transcript with its timed lines. 404 not_found when the call was not transcribed.
{
"status": "ok",
"callSid": "9b2f1c3e-0d4a-4e8b-9a51-6f0c2d7e8a10",
"transcript": {
"status": "done", "language": "english", "text": "Hello, I would like a refund for my order.",
"segments": [ { "start": 0.0, "end": 2.1, "text": "Hello," }, { "start": 2.1, "end": 6.0, "text": "I would like a refund for my order." } ],
"audioSecs": 75, "createdAt": "2026-11-12T10:04:11+03:00"
}
}
Download a recording
The recording as an audio file (usually MP3). Recordings are copied into Sozuri's storage within a few minutes of the
call, and this link serves that copy. 404 not_found when the call has no recording.
A link to share: add link=1 and the answer is JSON with a link anyone can open to play the
recording, with no API key, for 30 minutes. Use it to let a person listen in a browser without handing them your key.
Anyone holding the link can play the recording until expiresAt, so share it only with the person who needs it.
404 recording_unavailable when the recording cannot be fetched yet; try again in a few minutes.
{
"status": "ok",
"callSid": "9b2f1c3e-0d4a-4e8b-9a51-6f0c2d7e8a10",
"url": "https://sozuri.net/voice/recording/9b2f1c3e-0d4a-4e8b-9a51-6f0c2d7e8a10?expires=1794468600&signature=…",
"expiresAt": "2026-11-12T10:30:00+03:00"
}
Hang up a call
Ends one of your project's calls that has not ended. Send project in the body as usual.
{ "status": "ok", "endedAtProvider": true, "message": "The call was ended.", "call": { "callSid": "9b2f1c3e-…", "status": "failed", "...": "..." } }
endedAtProvider: true: the call was ended for both sides. Its final duration and price follow within seconds; look the call up for them.endedAtProvider: false: the call started too long ago to still be live, so only its record was closed (asfailed, at no charge).409 hangup_unsupported: this number's provider cannot end a live call from Sozuri. The call ends when either side hangs up, and its record closes then.409 already_ended: the call has already ended.- A call whose end is never reported is closed automatically, as
failedat no charge, once it is older than the longest a call can last.
List recent calls
Your project's calls, newest first, in the same shape as a single call without events.
| Query parameter | Description |
|---|---|
| limit | How many to return, 1 to 200. Default 50. |
| status | Only calls in this state, e.g. completed or no_answer. An unknown value is ignored. |
| tag | Only calls whose tag starts with this, e.g. reminder for every call placed with that tag. |
curl "https://sozuri.net/api/v1/voice/calls?project=your_project_name&status=no_answer&tag=reminder&limit=20" \
-H "Authorization: Bearer $SOZURI_API_KEY" -H "Accept: application/json"
{ "status": "ok", "count": 1, "calls": [ { "callSid": "0c7e5a12-8b3f-4d26-b1e4-2a9f6c0d3e57", "direction": "outbound", "status": "no_answer", "...": "..." } ] }
List your voice numbers
Your project's numbers that are active, suspended or still being requested.
{
"status": "ok",
"numbers": [
{ "number": "+254711000000", "type": "regular", "label": "Main line", "status": "active", "handlerType": "flow", "aiMode": false }
]
}
| Field | Values |
|---|---|
| type | regular, tollfree, premium or sip. |
| status | active (can call and be called), suspended (paused, e.g. an unpaid monthly fee) or requested (not assigned yet). Only an active number can be used as from. |
| handlerType | What answers a call to the number: say (play a message), flow (a call flow), queue (the call centre), forward (another phone) or webhook (your own URL). |
| aiMode | Reserved for numbers answered by an AI agent. Always false today. |
Call limits and the status webhook
A project admin sets these on Project → Voice, under Call limits and status webhook. The limits apply to every call placed with your API key (calls and voice OTP) and to test calls from the dashboard. They keep an API key to the job it was made for: if the key leaks, it can still only call the numbers you listed, as often as you allowed. Campaigns and the call centre, which only a signed-in member can start, are not limited by them.
| Setting | What it does |
|---|---|
| Numbers this project may call | An allow-list. Any other number is refused with not_allowed and not dialled. 0712…, 254712… and +254712… are the same number. Empty means any number. |
| Most calls in any hour | A request that would take the project past this many calls in the last 60 minutes is refused whole with 429 hourly_cap_reached. Empty means no limit. |
| Don't call the same number again within | A number called less than this many seconds ago is refused with recently_called, even with a new requestId. Use it as a second guard against calling a person twice. Empty means off. |
| Status webhook URL | Where Sozuri sends voice.status when each call your project placed ends. It must be on the public internet. |
| Record and transcribe every call | Every call that connects two people (a forwarded call, a call answered by your agents, a connect call) is recorded and turned into text. Callers always hear a notice first, in your wording or "This call may be recorded and transcribed."; on a call your agent places, the agent hears a reminder to tell the other person. Each transcript is charged per started minute of the call at your transcription rate, only once it exists; without enough balance a call is not transcribed until you top up. Recordings and transcripts are kept for 90 days. Read them on the call, through the API, or on Voice → Transcripts, filtered by date, agent, number and words said, with a CSV export. Messages and one-time codes are never recorded. A number set to Always record or Never record on the Numbers page follows its own setting instead (an always-recorded number on a project without this setting is recorded, with the notice, but not transcribed). |
The voice.status webhook
Sozuri POSTs this once when a call your project placed ends: answered and finished, not answered, or failed. You do not need it: looking the call up gives the same answer.
{
"event": "voice.status",
"callSid": "9b2f1c3e-0d4a-4e8b-9a51-6f0c2d7e8a10",
"requestId": "meeting-8812:5m",
"tag": "reminder_3f9a0c1b2d4e_1",
"from": "+254711000000",
"to": "254700000000",
"status": "completed",
"durationSecs": 12,
"price": "4.00",
"currency": "KES",
"answeredAt": "2026-11-11T06:55:03+00:00",
"endedAt": "2026-11-11T06:55:15+00:00"
}
statusiscompleted,no_answerorfailed(see Call statuses). Fields with no value are left out, never sent asnull; times are UTC.priceis a string, in KES, for the started minutes charged.-
It is signed like every Sozuri webhook, with the signing secret under Manage API → Callback URLs:
check the
X-Sozuri-Signatureheader over the exact body before you trust it. See Webhooks. - Answer with any
2xxwithin 8 seconds.
Call statuses
status | statusLabel | Meaning |
|---|---|---|
queued | Queued | Accepted, not dialled yet. |
ringing | Ringing | Dialling, or ringing at the other end. |
in_progress | In progress | Answered; the call is live. |
on_hold | On hold | The caller is waiting in your call-centre queue. |
completed | Completed | Answered and ended normally. |
no_answer | No answer | Rang out, was rejected or busy, or the number could not be reached. |
failed | Failed | The call could not be placed. |
Billing
- A call is charged when it ends, per minute at your project's voice rate: the answered duration, at least one minimum call, rounded up to the next whole increment. A 3-minute-41-second call on a per-minute rate is charged as 4 minutes.
- A call nobody answered lasts 0 seconds and costs nothing.
- A forwarded call is two calls: the caller's call to your number at your incoming rate, plus the call we place to the forward number at your outgoing rate, for the minutes that call lasted. The same applies when a call flow's Dial step or your call centre rings an agent's phone number. A forward that nobody answers adds nothing; a call to a desk phone or a browser phone is not a phone call and adds nothing.
priceis the total, and the call page shows the split. - Before dialling, your balance must cover one minimum call, or the request is refused with
402 insufficient_balanceand nothing is dialled. - The charge is on the call itself:
billableSecs,priceandcurrency. - On a postpay account, calls are priced and added to your invoice instead of taken from a balance.
Error responses
A refusal from the voice API looks like this:
{ "status": "error", "code": "no_voice_number", "message": "This project has no active voice number. Request one in the dashboard." }
| HTTP | code | Meaning |
|---|---|---|
| 200 | (not an error) | "duplicate": true: a request with this requestId was already placed. The body lists its calls; nothing was dialled. |
| 402 | insufficient_balance | Your balance does not cover one minimum call. Top up and retry. |
| 403 | not_allowed | The number is not on your project's allow-list. Do not retry. |
| 404 | not_found | No call with that callSid on your project. |
| 409 | recently_called | The number was called inside your project's repeat window. |
| 409 | already_ended | Hang up: the call has already ended. |
| 409 | hangup_unsupported | Hang up: this number's provider cannot end a live call from Sozuri; it ends when either side hangs up. |
| 409 | request_in_progress | Another copy of this requestId is being placed right now. Look it up in a few seconds rather than sending it again. |
| 429 | hourly_cap_reached | The call would take your project past its calls-per-hour limit. |
| 429 | busy | Another call request for your project was still being placed. Retry in a moment. |
| 429 | rate_limited | The voice provider is taking no more calls for a moment. Nothing was dialled. Retry after the number of seconds in the Retry-After header (also retryAfter on the rejected entry). |
| 422 | invalid_voice | voice is not a voice name. |
| 422 | invalid_connect | connect is not up to five phone numbers or one SIP address. |
| 422 | no_voice_number | Your project has no active voice number, or from is not one of them. |
| 422 | too_many_recipients | More than 100 numbers in to. |
| 422 | no_recipients | to held no number once blanks were removed. |
| 422 | invalid_code | Voice OTP: code has no digits. |
| 422 | voice_disabled | Voice calling is switched off on the platform for now. Retry later. |
| 422 | provider_not_configured | Your number cannot place calls yet. Contact support. |
| 422 | other | None of the numbers could be called; message says why for the first one. |
Two refusals come before the request reaches the voice API, and have the shape every Sozuri API uses for
them: a wrong key or project name is 401, and a missing or malformed field is 422
with the fields listed:
{
"error_code": "VALIDATION_FAILED",
"message": "The submitted data failed validation.",
"retryable": false,
"errors": { "code": ["The code field is required."] }
}
Ready to start sending?
Create a free Sozuri project, grab your API key, and send your first message in minutes.