Validating OTP Codes

Use POST /v1/otp/verify to check a plaintext code submitted by the end user. The endpoint is keyed on (phone_number, developer app, code) — the developer app is resolved from your bound X-API-Key, so you do not send app_key when the key is bound. There is no separate otp_id to track, and the call is the same regardless of whether the code was originally delivered via SMS, voice call, or WhatsApp. The server looks up the single active OTP for that phone within your Developer App and compares the bcrypt hash. The API enforces a hard cap of 3 attempts per active OTP. After the third wrong code the OTP is auto-locked and the user must request a new one. Drive your UI off data.remaining_attempts so the user always knows where they stand.

Endpoint

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

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

Request body

Field	Type	Required	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.
`code`	string	yes	Plaintext code submitted by the user.
`callback_url`	string (HTTPS)	no	Override or fallback callback URL if not set on request/resend.
`callback_secret`	string	no	Signing secret override; secret from request/resend is reused when omitted.

Trim whitespace and strip non-digits from the user’s input before submitting.

Success response

{
  "success": true,
  "message": "OTP verified successfully.",
  "data": { "verified_at": "2026-05-08T12:35:21.000000" },
  "status_code": 200
}

The OTP is marked used; subsequent verifies for the same code return success: false. If you passed callback_url on the original request or resend, Karibu also sends an async flake.verified webhook to that URL (best-effort). On max-attempt lockout, a flake.failed callback is sent instead. The synchronous response above is unchanged — see Flake lifecycle callbacks.

Handled errors

These are returned in the standard envelope with success: false. Branch on body.message and body.data.remaining_attempts:

`message`	`data.remaining_attempts`	When	Recommended UX
`"No valid OTP found"`	`0`	No active OTP for this `(phone, app)`, expired, or already used	Prompt the user to request a new code.
`"Invalid OTP code"`	`2`, `1`, `0`	Wrong code; counter decrements with each failed attempt.	Show “X attempts remaining”; allow retry until `0`.
`"Max verification attempts reached"`	`0`	3rd wrong attempt — OTP is now locked.	Disable the verify button; force the user to resend.
`"Invalid phone number"`	—	Malformed phone (non-digit, wrong shape).	Re-validate digits-only E.164 client-side before retrying.

Auth (401), host/scoping (403), and validation (422) errors share the same shape as on /v1/otp/request. See Error scenarios for the full matrix.

Code samples

curl -X POST https://karibu.briq.tz/v1/otp/verify \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "phone_number": "255712345678",
    "code": "123456"
  }'

import requests

BASE_URL = "https://karibu.briq.tz"
API_KEY  = "YOUR_API_KEY"
resp = requests.post(
    f"{BASE_URL}/v1/otp/verify",
    headers={"X-API-Key": API_KEY, "Content-Type": "application/json"},
    json={
        "phone_number": "255712345678",
        "code": "123456",
    },
    timeout=10,
)
body = resp.json()
if body.get("success"):
    print("Verified at", body["data"]["verified_at"])
else:
    print("Failed:", body["message"], "remaining:",
          body.get("data", {}).get("remaining_attempts"))

const BASE_URL = "https://karibu.briq.tz";
const API_KEY  = "YOUR_API_KEY";
const resp = await fetch(`${BASE_URL}/v1/otp/verify`, {
  method: "POST",
  headers: { "X-API-Key": API_KEY, "Content-Type": "application/json" },
  body: JSON.stringify({
    phone_number: "255712345678",
    code: "123456",
  }),
});
const body = await resp.json();
if (body.success) {
  console.log("Verified at", body.data.verified_at);
} else {
  console.log("Failed:", body.message, "remaining:", body.data?.remaining_attempts);
}

<?php
$baseUrl = "https://karibu.briq.tz";
$apiKey  = "YOUR_API_KEY";
$ch = curl_init("$baseUrl/v1/otp/verify");
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",
        "code"         => "123456",
    ]),
]);
$response = curl_exec($ch);
curl_close($ch);
$body = json_decode($response, true);
if ($body["success"] ?? false) {
    echo "Verified at " . $body["data"]["verified_at"];
} else {
    echo "Failed: " . $body["message"];
}

Best practices

Branch on success first, then on data.remaining_attempts. Treat 0 as a hard lockout — the user must resend.
Never log the plaintext code. Don’t echo it from your verify form, store it in analytics, or include it in error reports.
Strip whitespace and non-digits from the user’s input before submitting to avoid spurious “Invalid OTP code” responses.
Use the same bound API key (and Developer App) that issued the OTP. Cross-app verifies always fail with "No valid OTP found".

What’s next

For “Resend code” buttons, idempotent invalidation on logout, and live countdowns, see Managing OTP lifecycle.
For payload-level detail and the full error matrix, see the Karibu OTP API reference.

Overview

Working Environment

Messaging

OTP

WhatsApp

Voice

Endpoint

Request body

Success response

Handled errors

Code samples

Best practices

What’s next

​Endpoint

​Request body

​Success response

​Handled errors

​Code samples

​Best practices

​What’s next

Endpoint

Request body

Success response

Handled errors

Code samples

Best practices

What’s next