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.

POST https://sozuri.net/api/v1/voice/calls

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 a message (read out instead) or a connect (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 an apiKey field in the query string or body) plus project, 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: 201 means at least one call was placed.

Place a call

POST https://sozuri.net/api/v1/voice/calls
FieldRequiredTypeDescription
projectYesStringYour project's name.
toYesString or arrayWho 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.
fromNoStringWhich of your active voice numbers to call from. Leave it out to use your project's first active number.
tagNoStringUp 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.
messageNoStringUp 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.
voiceNoStringThe 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.
requestIdNoStringYour 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.
connectNoStringClick-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" }
  ]
}
  • callSid is the call's id: keep it to look the call up.
  • tag is 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 new requestId.
  • Each number is dialled separately, so some can be refused while others ring. When that happens the answer is still 201 and carries rejected, 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's code and message (see Error responses); a refusal of one of your numbers by your project's call limits also lists them in rejected.
  • testMode is true only when the call was simulated and nobody's phone rang. It is false on a live project.

Read a one-time code (voice OTP)

POST https://sozuri.net/api/v1/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.

FieldRequiredTypeDescription
projectYesStringYour project's name.
toYesStringThe one number to call, international format. Up to 32 characters.
codeYesStringThe 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).
brandNoStringThe name read before the code, up to 60 characters. Default Sozuri.
repeatNoIntegerHow many times the code is read, 1 to 3. Default 2.
voiceNoStringA 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.
fromNoStringWhich 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

GET https://sozuri.net/api/v1/voice/calls/{callSid}

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" }
    ]
  }
}
FieldDescription
directionoutbound (you placed it) or inbound (someone called your number).
status / statusLabelThe call's state and its label: see Call statuses.
durationSecsHow long the call lasted once answered. null until it ends.
billableSecs, price, currencyWhat the call was charged, set when it ends (see Billing). null while it is in progress.
requestIdThe requestId the call was placed with, or null.
recordingUrlWhere 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.
eventsThe 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.
answersEvery 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

GET https://sozuri.net/api/v1/voice/calls/{callSid}/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

GET https://sozuri.net/api/v1/voice/calls/{callSid}/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

POST https://sozuri.net/api/v1/voice/calls/{callSid}/hangup

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 (as failed, 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 failed at no charge, once it is older than the longest a call can last.

List recent calls

GET https://sozuri.net/api/v1/voice/calls

Your project's calls, newest first, in the same shape as a single call without events.

Query parameterDescription
limitHow many to return, 1 to 200. Default 50.
statusOnly calls in this state, e.g. completed or no_answer. An unknown value is ignored.
tagOnly 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

GET https://sozuri.net/api/v1/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 }
  ]
}
FieldValues
typeregular, tollfree, premium or sip.
statusactive (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.
handlerTypeWhat 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).
aiModeReserved 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.

SettingWhat it does
Numbers this project may callAn 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 hourA 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 withinA 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 URLWhere Sozuri sends voice.status when each call your project placed ends. It must be on the public internet.
Record and transcribe every callEvery 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"
}
  • status is completed, no_answer or failed (see Call statuses). Fields with no value are left out, never sent as null; times are UTC.
  • price is 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-Signature header over the exact body before you trust it. See Webhooks.
  • Answer with any 2xx within 8 seconds.

Call statuses

statusstatusLabelMeaning
queuedQueuedAccepted, not dialled yet.
ringingRingingDialling, or ringing at the other end.
in_progressIn progressAnswered; the call is live.
on_holdOn holdThe caller is waiting in your call-centre queue.
completedCompletedAnswered and ended normally.
no_answerNo answerRang out, was rejected or busy, or the number could not be reached.
failedFailedThe 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. price is 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_balance and nothing is dialled.
  • The charge is on the call itself: billableSecs, price and currency.
  • 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." }
HTTPcodeMeaning
200(not an error)"duplicate": true: a request with this requestId was already placed. The body lists its calls; nothing was dialled.
402insufficient_balanceYour balance does not cover one minimum call. Top up and retry.
403not_allowedThe number is not on your project's allow-list. Do not retry.
404not_foundNo call with that callSid on your project.
409recently_calledThe number was called inside your project's repeat window.
409already_endedHang up: the call has already ended.
409hangup_unsupportedHang up: this number's provider cannot end a live call from Sozuri; it ends when either side hangs up.
409request_in_progressAnother copy of this requestId is being placed right now. Look it up in a few seconds rather than sending it again.
429hourly_cap_reachedThe call would take your project past its calls-per-hour limit.
429busyAnother call request for your project was still being placed. Retry in a moment.
429rate_limitedThe 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).
422invalid_voicevoice is not a voice name.
422invalid_connectconnect is not up to five phone numbers or one SIP address.
422no_voice_numberYour project has no active voice number, or from is not one of them.
422too_many_recipientsMore than 100 numbers in to.
422no_recipientsto held no number once blanks were removed.
422invalid_codeVoice OTP: code has no digits.
422voice_disabledVoice calling is switched off on the platform for now. Retry later.
422provider_not_configuredYour number cannot place calls yet. Contact support.
422otherNone 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.