Requesting OTP Codes

Use POST /v1/otp/request to generate a fresh numeric OTP and deliver it to a phone via SMS (default), voice call, or WhatsApp. Requests are scoped to the Developer App bound to your X-API-Key — Karibu resolves the app automatically; you do not send app_key in the body when the key is bound. Calling it always invalidates any prior unused, unexpired OTP for the same (phone, app) before issuing the new one, so there is never more than one active OTP for a phone within an app. Each channel has its own payload shape. The fields sender_id and message_template are SMS-only — they exist for SMS branding/wording control and are silently ignored on "call" and "whatsapp". Voice reads the code via TTS; WhatsApp routes through the platform-managed briq_otp template with automatic sender resolution. Default to "sms" for the broadest reach. Use "call" for SMS-restricted regions or accessibility needs, and "whatsapp" for app-installed users with chat-first habits.

Endpoint

POST https://karibu.briq.tz/v1/otp/request

Headers: X-API-Key (required — bind to a Developer App for OTP), Content-Type: application/json (required).

Common request fields

These fields are the same on every channel:

Field	Type	Required	Default	Notes
`phone_number`	string (E.164 digits)	yes	—	Digits only, no `+`. e.g. `255712345678`.
`app_key`	string	no	—	Omit when API key is bound to a developer app. Legacy unbound keys may send this or use `X-App-ID` instead.
`delivery_method`	string	yes (recommended)	`"sms"`	One of `"sms"`, `"call"`, `"whatsapp"`.
`otp_length`	int	no	`6`	Length of the generated code.
`minutes_to_expire`	int	no	`10`	TTL in minutes.
`callback_url`	string (HTTPS)	no	—	Optional per-request webhook URL for async flake lifecycle events. Active for this OTP’s lifetime.
`callback_secret`	string	no	—	Optional HMAC secret for `X-Briq-Signature` on callbacks.

callback_url and callback_secret are optional. When set, Karibu associates them with this OTP and POSTs flake.verified or flake.failed to your URL after verify outcomes. See Flake lifecycle callbacks for the full flow and testing guide.

Success response

The same shape on every channel:

{
  "success": true,
  "message": "OTP Code sent successfully.",
  "data": { "expires_at": "2026-05-08T12:34:56.000000" },
  "status_code": 200
}

The plaintext code is never returned. The recipient receives it via SMS, voice call, or WhatsApp only. Don’t try to capture or log it on the server.

Channel-specific payload & code samples

SMS
Voice call
WhatsApp

Default channel. Customisable per call via sender_id and message_template.Channel-specific fields:

Field	Type	Required	Default	Notes
`sender_id`	string	no	`OTP_DEFAULT_SENDER_ID`	The SMS sender ID shown to the recipient. Must be approved for your account.
`message_template`	string	no	server default	Must contain `{code}`. `{expiry}` is also substituted. Falls back if `{code}` missing.

Exact payload:

{
  "phone_number": "255712345678",
  "delivery_method": "sms",
  "otp_length": 6,
  "minutes_to_expire": 10,
  "sender_id": "BRIQ OTP",
  "message_template": "Your verification code is {code}. It expires in {expiry} minutes."
}

curl -X POST https://karibu.briq.tz/v1/otp/request \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "phone_number": "255712345678",
    "delivery_method": "sms",
    "otp_length": 6,
    "minutes_to_expire": 10,
    "sender_id": "BRIQ OTP",
    "message_template": "Your verification code is {code}. It expires in {expiry} minutes."
  }'

import requests

BASE_URL = "https://karibu.briq.tz"
API_KEY  = "YOUR_API_KEY"
resp = requests.post(
    f"{BASE_URL}/v1/otp/request",
    headers={"X-API-Key": API_KEY, "Content-Type": "application/json"},
    json={
        "phone_number": "255712345678",
        "delivery_method": "sms",
        "otp_length": 6,
        "minutes_to_expire": 10,
        "sender_id": "BRIQ OTP",
        "message_template": "Your verification code is {code}. It expires in {expiry} minutes.",
    },
    timeout=15,
)
print(resp.status_code, resp.json())

const BASE_URL = "https://karibu.briq.tz";
const API_KEY  = "YOUR_API_KEY";
const resp = await fetch(`${BASE_URL}/v1/otp/request`, {
  method: "POST",
  headers: {
    "X-API-Key": API_KEY,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    phone_number: "255712345678",
    delivery_method: "sms",
    otp_length: 6,
    minutes_to_expire: 10,
    sender_id: "BRIQ OTP",
    message_template: "Your verification code is {code}. It expires in {expiry} minutes.",
  }),
});
console.log(resp.status, await resp.json());

<?php
$baseUrl = "https://karibu.briq.tz";
$apiKey  = "YOUR_API_KEY";
$ch = curl_init("$baseUrl/v1/otp/request");
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_POST           => true,
    CURLOPT_HTTPHEADER     => [
        "X-API-Key: $apiKey",
        "Content-Type: application/json",
    ],
    CURLOPT_POSTFIELDS     => json_encode([
        "phone_number"      => "255712345678",
        "delivery_method"   => "sms",
        "otp_length"        => 6,
        "minutes_to_expire" => 10,
        "sender_id"         => "BRIQ OTP",
        "message_template"  => "Your verification code is {code}. It expires in {expiry} minutes.",
    ]),
]);
$response = curl_exec($ch);
$status   = curl_getinfo($ch, CURLINFO_HTTP_CODE);
curl_close($ch);
echo $status . "\n" . $response;

The platform calls the recipient and reads the code via TTS. There is no sender_id or message_template field — both are SMS-only and ignored on this channel.Channel-specific fields: none.Exact payload:

{
  "phone_number": "255712345678",
  "delivery_method": "call",
  "otp_length": 6,
  "minutes_to_expire": 10
}

curl -X POST https://karibu.briq.tz/v1/otp/request \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "phone_number": "255712345678",
    "delivery_method": "call",
    "otp_length": 6,
    "minutes_to_expire": 10
  }'

import requests

BASE_URL = "https://karibu.briq.tz"
API_KEY  = "YOUR_API_KEY"
resp = requests.post(
    f"{BASE_URL}/v1/otp/request",
    headers={"X-API-Key": API_KEY, "Content-Type": "application/json"},
    json={
        "phone_number": "255712345678",
        "delivery_method": "call",
        "otp_length": 6,
        "minutes_to_expire": 10,
    },
    timeout=15,
)
print(resp.status_code, resp.json())

const BASE_URL = "https://karibu.briq.tz";
const API_KEY  = "YOUR_API_KEY";
const resp = await fetch(`${BASE_URL}/v1/otp/request`, {
  method: "POST",
  headers: { "X-API-Key": API_KEY, "Content-Type": "application/json" },
  body: JSON.stringify({
    phone_number: "255712345678",
    delivery_method: "call",
    otp_length: 6,
    minutes_to_expire: 10,
  }),
});
console.log(resp.status, await resp.json());

<?php
$baseUrl = "https://karibu.briq.tz";
$apiKey  = "YOUR_API_KEY";
$ch = curl_init("$baseUrl/v1/otp/request");
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_POST           => true,
    CURLOPT_HTTPHEADER     => [
        "X-API-Key: $apiKey",
        "Content-Type: application/json",
    ],
    CURLOPT_POSTFIELDS     => json_encode([
        "phone_number"      => "255712345678",
        "delivery_method"   => "call",
        "otp_length"        => 6,
        "minutes_to_expire" => 10,
    ]),
]);
echo curl_exec($ch);
curl_close($ch);

Delivers the OTP through the platform-managed briq_otp WhatsApp Business template. There is no sender_id or message_template field — sender resolution is automatic and the wording is fixed by the approved Meta template.Sender resolution order (you don’t pass any sender field; the dispatcher picks one):

A non-default WhatsApp sender owned by your developer user with an APPROVED briq_otp template.
The sender whose Infobip phone_number_id matches the platform-wide WHATSAPP_PHONE_NUMBER_ID env value.
The legacy is_default = TRUE sender row.

Channel-specific fields: none.Exact payload:

{
  "phone_number": "255712345678",
  "delivery_method": "whatsapp",
  "otp_length": 6,
  "minutes_to_expire": 10
}

curl -X POST https://karibu.briq.tz/v1/otp/request \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "phone_number": "255712345678",
    "delivery_method": "whatsapp",
    "otp_length": 6,
    "minutes_to_expire": 10
  }'

import requests

BASE_URL = "https://karibu.briq.tz"
API_KEY  = "YOUR_API_KEY"
resp = requests.post(
    f"{BASE_URL}/v1/otp/request",
    headers={"X-API-Key": API_KEY, "Content-Type": "application/json"},
    json={
        "phone_number": "255712345678",
        "delivery_method": "whatsapp",
        "otp_length": 6,
        "minutes_to_expire": 10,
    },
    timeout=15,
)
print(resp.status_code, resp.json())

const BASE_URL = "https://karibu.briq.tz";
const API_KEY  = "YOUR_API_KEY";
const resp = await fetch(`${BASE_URL}/v1/otp/request`, {
  method: "POST",
  headers: { "X-API-Key": API_KEY, "Content-Type": "application/json" },
  body: JSON.stringify({
    phone_number: "255712345678",
    delivery_method: "whatsapp",
    otp_length: 6,
    minutes_to_expire: 10,
  }),
});
console.log(resp.status, await resp.json());

<?php
$baseUrl = "https://karibu.briq.tz";
$apiKey  = "YOUR_API_KEY";
$ch = curl_init("$baseUrl/v1/otp/request");
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_POST           => true,
    CURLOPT_HTTPHEADER     => [
        "X-API-Key: $apiKey",
        "Content-Type: application/json",
    ],
    CURLOPT_POSTFIELDS     => json_encode([
        "phone_number"      => "255712345678",
        "delivery_method"   => "whatsapp",
        "otp_length"        => 6,
        "minutes_to_expire" => 10,
    ]),
]);
echo curl_exec($ch);
curl_close($ch);

WhatsApp-specific 400s. If the dispatcher cannot resolve a sender + APPROVED briq_otp template (e.g. the platform default isn’t configured, or a custom one is in DRAFT/PAUSED), the response is success: false with a message describing which check failed (NO_DEFAULT_SENDER, TEMPLATE_NOT_APPROVED). Fall back to SMS in your client when this happens.

Error responses

HTTP	Cause	Shape
400	invalid phone, send failure, unsupported `delivery_method`, WhatsApp dispatcher errors (`NO_DEFAULT_SENDER`, `TEMPLATE_NOT_APPROVED`)	envelope with `success: false` and a `message`
401	missing/expired `X-API-Key`	`{"detail": "Invalid or expired API key"}`
403	wrong host, API key not bound to a developer app, `app_key`/`X-App-ID` mismatch with the bound app, workspace not dev-accessible	`{"detail": "..."}`
422	malformed body (e.g. non-digit phone, missing fields)	FastAPI validation error

For the full cross-endpoint error reference, see Error scenarios.

Best practices

Validate the phone client-side before calling the API: digits-only, country code present, plausible length.
Store data.expires_at so your UI can drive a countdown timer; consider polling /v1/otp/status instead of triggering re-sends speculatively.
Cascade channels for reliability. A common pattern: try "whatsapp" first; on a dispatcher 400, fall back to "sms"; offer "call" as a manual third option.
Don’t promise custom WhatsApp wording. The briq_otp template is fixed by Meta — sender_id and message_template are silently ignored on "whatsapp" and "call".
Rate-limit your own users. The API does not enforce per-phone request limits — your application should.
Never log the plaintext code. It only exists in transit to the recipient.

What’s next

Once the code is sent, verify what the user submits — see Validating OTP codes.
For “Resend code” buttons, lockouts on logout, and live countdowns, see Managing OTP lifecycle.

Overview

Working Environment

Messaging

OTP

WhatsApp

Voice

Endpoint

Common request fields

Success response

Channel-specific payload & code samples

Error responses

Best practices

What’s next

​Endpoint

​Common request fields

​Success response

​Channel-specific payload & code samples

​Error responses

​Best practices

​What’s next

Endpoint

Common request fields

Success response

Channel-specific payload & code samples

Error responses

Best practices

What’s next