Send a code you generate on WhatsApp, SMS or a voice call, in the order you choose. Each channel goes only when the one before did not get the code there, and you can check the result or receive it as a webhook. Same API key and project name as SMS.

• How it works
• Before you start
• Send a code
• The response
• When each channel goes
• Check a code
• Statuses and reasons
• The otp.status webhook
• What happens to the code
• Billing and rate limits
• Error responses

How it works

• You generate the code and you check it. Sozuri only delivers it. When the person types the code into your app, compare it with the one you stored.
• channels sets the order. Use whatsapp, sms and voice, in the order to try them. WhatsApp can only come first and voice only last. These orders are allowed: ["whatsapp", "sms", "voice"], ["whatsapp", "sms"] (the default), ["whatsapp", "voice"], ["sms", "voice"], or any one channel on its own.
• The next channel goes only when it is needed. That happens straight away when a channel refuses the code or WhatsApp reports the message failed. Otherwise it happens after fallback_after seconds if no delivery has been confirmed. See When each channel goes.
• Each channel is used at most once. Once WhatsApp confirms delivery, nothing more is sent.

Before you start

Authenticate as for SMS: send your API key as Authorization: Bearer <key>, or as an apiKey field in the query string or body, plus project, your project's name. See Authentication.

Send a code

WhatsApp, then SMS, then a call:

curl -X POST https://sozuri.net/api/v1/otp \
  -H "Authorization: Bearer $SOZURI_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{
    "project": "your_project_name",
    "to": "254700000000",
    "code": "482913",
    "channels": ["whatsapp", "sms", "voice"],
    "fallback_after": 30,
    "sms": { "from": "YourSenderID", "text": "{code} is your Acme login code." },
    "voice": { "brand": "Acme" },
    "callback_url": "https://your-app.example/hooks/otp"
  }'

SMS only:

{ "project": "your_project_name", "to": "254700000000", "code": "482913",
  "channels": ["sms"], "sms": { "from": "YourSenderID" } }

SMS, then a call if the SMS was not delivered within a minute:

{ "project": "your_project_name", "to": "254700000000", "code": "4821",
  "channels": ["sms", "voice"], "fallback_after": 60,
  "sms": { "from": "YourSenderID" }, "voice": { "brand": "Acme", "repeat": 3 } }

The response

200 OK means the request was accepted. The first channel has already been tried before the answer arrives. The answer is the OTP as it stands at that moment:

{
  "otp": {
    "id": "otp_5f0c2a7d9e1b4c3a8f6d2e10",
    "status": "sent",
    "channel": "whatsapp",
    "to": "254700000000",
    "channels": ["whatsapp", "sms", "voice"],
    "whatsapp": { "status": "pending" },
    "sms": { "from": "YourSenderID", "type": "transactional" },
    "voice": { "status": "waiting" },
    "fallback": { "after": 30 },
    "createdAt": "2026-11-11T09:00:00+00:00"
  }
}

When each channel goes

Every wait is fallback_after seconds (F), counted from the moment the channel before went:

With ["whatsapp", "sms", "voice"] and the default 30 seconds, WhatsApp goes at once. If WhatsApp has not delivered, the SMS goes at about 30 seconds, and if the SMS has not been confirmed delivered, the call goes at about 60 seconds. If WhatsApp fails or refuses the message, everything moves earlier by the time saved.

• How exact the timing is. A move normally happens within a few seconds of its due time. If Sozuri is delayed, it catches up within about a minute and a half. A move that would be more than five minutes late is never made, because by then the code is too old to be useful. The code is then decided as it stands: channel is the last channel that went, and nothing more is sent.
• An SMS that is not delivered still waits. An "undelivered" report that arrives before F is read at F; it does not start the call early.
• Choose F for your network's delivery reports. If an SMS delivery report takes longer than F to come back, the call goes to someone who may already have the SMS. A longer F avoids that, but the person waits longer.
• WhatsApp's own delivery limit. An authentication template has a delivery time limit (30 to 900 seconds, message_send_ttl_seconds). After that limit WhatsApp stops trying and reports the message failed, and that report moves the code on. Set the limit close to F. Then a WhatsApp message that missed its chance is dropped, rather than arriving after the SMS.

Check a code

Answers the same otp object as the response, as it is now. An id that belongs to another project, or is not an OTP id, answers 404 otp_not_found. If you did not give a callback_url, poll this every few seconds until finishedAt appears.

{
  "otp": {
    "id": "otp_5f0c2a7d9e1b4c3a8f6d2e10",
    "status": "delivered",
    "channel": "sms",
    "to": "254700000000",
    "channels": ["whatsapp", "sms", "voice"],
    "whatsapp": { "status": "failed", "error": "undeliverable" },
    "sms": { "from": "YourSenderID", "type": "transactional", "messageId": "8f3c2a1e9b7d4c6f0a5e2d1b3c4f5a6b7c8d9e0f" },
    "voice": { "status": "waiting" },
    "fallback": { "after": 30, "reason": "whatsapp_failed", "at": "2026-11-11T09:00:04+00:00" },
    "createdAt": "2026-11-11T09:00:00+00:00",
    "finishedAt": "2026-11-11T09:00:34+00:00"
  }
}

Statuses and reasons

When a code is decided, finishedAt is set and the webhook goes. That happens when WhatsApp or the SMS delivers it (delivered), when it goes to its last channel (sent), or when no channel can take it (failed). There is one exception: when WhatsApp is the last channel, the code is decided by WhatsApp's own report, delivered or failed. An SMS that is the last channel is decided when it goes, as sent. Its delivery report then comes through your SMS log and SMS delivery webhooks, under sms.messageId.

The otp.status webhook

If you give a callback_url, one POST arrives when the code is decided. It is sent once: a later change, such as a late WhatsApp delivery or a read, updates the OTP you check but sends nothing more.

{
  "event": "otp.status",
  "id": "otp_5f0c2a7d9e1b4c3a8f6d2e10",
  "status": "sent",
  "channel": "sms",
  "to": "254700000000",
  "channels": ["whatsapp", "sms", "voice"],
  "reason": "whatsapp_failed",
  "timestamp": "2026-11-11T09:00:31+00:00"
}

• channel is missing when no channel took the code (failed), and reason is missing when the first channel did the job.
• timestamp is when the code was decided (UTC). The code itself is never in the body.
• It is signed like every Sozuri callback, with an X-Sozuri-Signature header. The signing secret is under Manage API → Callback URLs → Webhook security, and the webhooks page explains how to check it. Answer with any 2xx.

What happens to the code

• The code is never returned by the API, never written to a log, and never in the webhook.
• In your WhatsApp conversations the message shows as •••••• is your verification code., without the code.
• The call is never recorded.
• An SMS is an ordinary SMS, so its text, code included, appears in your SMS log like any message you send.
• Sozuri keeps the code, encrypted, only while a later channel might still need it. It is deleted as soon as the code is decided.

Billing and rate limits

• You pay for each channel used, at that channel's own rate: a WhatsApp authentication message, an SMS, and a call. A code that WhatsApp delivered in time costs one WhatsApp message. A code that also needed the SMS and the call costs all three.
• POST /v1/otp takes up to 300 requests a minute per project, and GET /v1/otp/{id} up to 600. Past that the answer is 429; wait and retry.

Error responses

An OTP refusal names the field to fix in errors:

{
  "error": {
    "code": "invalid_request",
    "message": "The request needs changes.",
    "status": 422,
    "errors": { "channels": "channels is an ordered list of whatsapp, sms and voice, e.g. [\"whatsapp\", \"sms\", \"voice\"]: whatsapp can only come first and voice only last." }
  }
}

Three refusals come from the platform rather than the OTP API, so they have the platform's shape: { "error_code", "message", "retryable" }. They are 401 AUTHENTICATION_FAILED (check the API key and project), 422 VALIDATION_FAILED (a field is missing or has the wrong type; errors lists them) and 429 RATE_LIMITED.