Tambua API documentation

Overview

The Tambua API is a JSON REST API. Every request goes to one base URL over HTTPS.

The flow is always the same: you send an OTP to a phone number or email address, we deliver it, and the user types the code into your app. You then verify the code with the otp_token we gave you. Codes are single-use and expire. We store only a salted hash of the code.

Authentication

Create API keys in the consoleunder Keys & webhooks. Send the key as a Bearer token on every request. Keys are either test (free, never reaches a handset) or live (bills your wallet). Keep keys on your server, never in a mobile app or browser bundle.

Authorization: Bearer $TAMBUA_KEY

Scopes

Quickstart

Send a code, then verify it. Replace the number with your own.

curl -X POST https://api.tambua.me/v1/otp/send \
  -H "Authorization: Bearer $TAMBUA_KEY" \
  -H "Content-Type: application/json" \
  -d '{"phone":"+254712345678","purpose":"login"}'

The response contains an otp_token. Keep it until the user submits the code:

curl -X POST https://api.tambua.me/v1/otp/verify \
  -H "Authorization: Bearer $TAMBUA_KEY" \
  -H "Content-Type: application/json" \
  -d '{"otp_token":"<otp_token from the send response>","code":"482910"}'

Node.js SDK

The same flow with the official SDK (zero dependencies, Node 18+, TypeScript types included). Failures throw a TambuaError with the stable error code, and webhooks.constructEvent verifies webhook signatures for you.

npm install tambua

import { Tambua } from "tambua";

const tambua = new Tambua(process.env.TAMBUA_KEY);

const sent = await tambua.otp.send({ phone: "+254712345678", purpose: "login" });
// keep sent.otp_token until the user submits the code

const ok = await tambua.otp.check({ otp_token: sent.otp_token, code: "482910" }); // true or false

Send an OTP

Send one request object, or an array of up to many request objects (the body may also be { "items": [...] }). An array returns one result per item.

Request body

Response

A single request returns 201 Created. An array returns 201 if every item succeeded, otherwise 207 with a per-item result.

{
  "otp_id": "tambua_otp_8f3a9c12",
  "status": "pending",
  "channel": "sms",
  "delivery": { "status": "sent" },
  "attempts": { "used": 0, "max": 5 },
  "expires_at": "2026-05-25T14:37:24.110Z",
  "template": { "id": "sms-standard", "custom": {} },
  "otp_token": "eyJhbGciOi..."
}

Verify an OTP

You can also call POST /v1/otp/{otp_id} with the same body.

{
  "verified": true,
  "otp_id": "tambua_otp_8f3a9c12",
  "status": "verified",
  "attempts": { "used": 1, "max": 5 },
  "verified_at": "2026-05-25T14:32:24.108Z"
}

A wrong code returns 400 invalid_code and counts as an attempt. After the maximum, the OTP is locked and returns 429 max_attempts_exceeded. An expired code returns 401 expired_token. Calling verify again for an OTP that is already verified returns the same verified response, so make your own login step single-use.

Delivery journey (automatic fallback)

A delivery journey is an ordered list of up to three channels per app, for example SMS, then WhatsApp, then Voice. Set it in the console under Settings, Delivery journey. When a request has no channel, Tambua tries the steps in order until one delivers.

• Failure fallback. If a channel fails to send, or the carrier reports a failure, the next step runs immediately.
• Timed fallback (optional). Each step can instead fall back after 1, 2, 5 or 10 minutes without a delivery receipt.
• One OTP. The same code and the same otp_token are used on every attempt. You verify once.
• Billing. Only attempts a carrier accepts are billed. Failed attempts are free. A step is skipped if the wallet cannot cover it.
• Forcing a channel. Passing channel skips the journey and uses exactly that channel.
• Country limits. A step can be limited to chosen countries. Steps that need an email address are skipped if none was sent.

{
  "otp_id": "tambua_otp_8f3a9c12",
  "channel": "whatsapp",
  "journey": {
    "step": 2,
    "steps": 3,
    "attempts": [
      { "step": 1, "channel": "sms",      "status": "failed" },
      { "step": 2, "channel": "whatsapp", "status": "sent" }
    ]
  }
}

Each fallback also fires an otp.fallback_triggeredwebhook, and the request shows a "Fallback used" marker in the console logs.

Channels

Reverse OTP is available in early access. Telegram, USSD and Shortcode are coming soon.

Test mode

Test keys never reach a handset and never charge your wallet. The send response includes test_code, so you can complete the whole flow, send, receive and verify, with no phone. Switch to a live key when you are ready. Nothing else changes.

Webhooks

We POST signed JSON events to your endpoint when an OTP changes state. Failed deliveries are retried with exponential backoff for up to 24 hours. Every delivery, with its payload and your server's response, is visible in the console under Keys & webhooks, Deliveries, where you can retry it.

{
  "id": "tambua_evt_88f0a64",
  "type": "otp.verified",
  "created": "2026-05-25T14:32:24.110Z",
  "data": {
    "otp_id": "tambua_otp_8f3a9c12",
    "purpose": "login",
    "channel": "sms",
    "verified_at": "2026-05-25T14:32:24.108Z"
  }
}

Verify the signature

Each request carries X-Tambua-Signature: t=<unix>,v1=<hex> and X-Tambua-Event. The signature is an HMAC-SHA256, using your signing secret, of the string `${t}.${rawBody}`. Compute it over the raw request body and compare in constant time. Reject old timestamps to stop replays.

import { createHmac, timingSafeEqual } from "node:crypto";

function verifyWebhook(rawBody, header, secret, toleranceSec = 300) {
  const parts = Object.fromEntries(header.split(",").map((p) => p.split("=")));
  if (Math.abs(Date.now() / 1000 - Number(parts.t)) > toleranceSec) return false;
  const expected = createHmac("sha256", secret)
    .update(`${parts.t}.${rawBody}`)
    .digest("hex");
  return timingSafeEqual(Buffer.from(expected), Buffer.from(parts.v1 || ""));
}

Manage endpoints by API

Requires the manage_webhooks scope.

Logs

Requires the read_logs scope. Returns up to 10 records per page, newest first.

{
  "data": [
    {
      "otp_id": "tambua_otp_8f3a9c12",
      "status": "verified",
      "delivery_status": "delivered",
      "channel": "sms",
      "purpose": "login",
      "created_at": "2026-05-25T14:32:20.000Z",
      "journey": null
    }
  ],
  "pagination": { "limit": 10, "next_before": "2026-05-25T14:32:20.000Z" }
}

Errors

Errors use a standard HTTP status and a JSON body with a stable code. Branch on error, not on text.

{ "error": "insufficient_balance", "details": {} }

Settings and limits

Defaults are set per app in the console under Settings, Verification. You can override them per request where noted.