Two calls between you and a verified user.

Quickstart

1. 01

   Create an API key

   Create a tk_test_ key in your application's Keys tab. It works before application approval.

2. 02

   Send the code

   POST to /v1/verify/start with a destination, and you get back an id and an expiry.

3. 03

   Check the code

   POST to /v1/verify/check with the same id and the code the user typed.

Channels

Verification codes over WhatsApp are coming soon; SMS works today. WhatsApp template messages, such as order updates and reminders, have their own endpoint below, from your own connected number.

Authentication

Pass your key in the Authorization header as a Bearer token, or in the x-api-key header if that is not possible. When both are present, Authorization wins.

Key scopes and hardening

Set when you create the key in the console. All optional.

• `expires_at` (optional): once it passes, every call with that key answers `401 key_expired`, checked right after the key is recognised, before anything else.
• `ip_allowlist` (optional): exact IPs and/or CIDR ranges, IPv4 and IPv6. Empty or absent allows every address; a caller outside the list gets `403 ip_not_allowed`.
• Access: a key has full access, which covers every product and any product added later, or custom access, which covers only what it was granted, product by product. Verify: none, check only, or send and check. Notifications: none, read only, or send. Whatever its access, a key is a server-side secret: never put one in a browser or a mobile app.
• The scopes behind those levels: `verify:check` calls `POST /v1/verify/check` and `GET /v1/verify/{id}`. `verify:send` calls `POST /v1/verify/start`, `POST /v1/verify/{id}/resend` and `POST /v1/verify/{id}/cancel`, and includes `verify:check`. `notifications:read` calls `GET /v1/whatsapp/messages/{id}`, `GET /v1/whatsapp/templates` and `GET /v1/whatsapp/templates/{template_id}`. `notifications:send` calls `POST /v1/whatsapp/messages`, and includes `notifications:read`. One more scope is not a level of that page: `notifications:templates` calls `POST /v1/whatsapp/templates`, `PATCH /v1/whatsapp/templates/{template_id}` and `DELETE /v1/whatsapp/templates/{template_id}`, and includes `notifications:read`. No key made on the API keys page holds it, full access included: those three calls answer such a key `403 insufficient_scope`. A connected app's key holds it.
• A call outside the key's access answers `403` with the body `{"error":"insufficient_scope"}`, and the response header names the scope the call needs: `WWW-Authenticate: Bearer error="insufficient_scope", scope="verify:send"`. It is judged right after the key is recognised: after `unauthorized`, `key_expired` and `ip_not_allowed`, before `account_not_active` and the request's shape.
• A check-only key created before access was set product by product works as it always did: it holds `verify:check` and `notifications:read`, so it checks codes and reads statuses and templates on both products, and sends on neither.
• A test key cannot be granted Notifications: WhatsApp has no sandbox, and `/v1/whatsapp/*` refuses every test key.
• Email: none, read only, or send. `email:read` calls `GET /v1/email/messages/{id}`. `email:send` calls `POST /v1/email/messages`, and includes `email:read`. A test key cannot be granted Email: there is no e-mail sandbox, and `/v1/email/*` refuses every test key.
• Set at creation on the application's API keys page in the client console (Create a key). A key's access cannot be changed afterwards: create a new key with the access you need. A partner rotating its key can set an expiry and an IP allowlist too; a partner key always has full access and cannot be narrowed.

Sandbox

Create a tk_test_ key in the dashboard before application approval. It uses the same endpoints and request formats as a live key.

• Created by you, before application approval: on the application's API keys page (Create a key, type Test), or made for you by the first send from Verify → Test in the console.
• Calls the exact same endpoints with the exact same request/response shapes as a live key.
• Sends real messages, but only to one number: the phone the account owner verified at signup. No other destination can be added.
• Every message carries an unremovable [TEST]/[تجريبي] stamp.
• Charged like any other send, from the same prepaid balance, and capped at 10 lifetime sends per application so testing cannot consume the whole welcome credit.
• WhatsApp has no sandbox: `/v1/whatsapp/*` refuses every test key, with `403 live_key_required` (or `403 insufficient_scope` for a test key with custom access, which never holds Notifications).

Autofill-ready messages

The autofill domain comes from your reviewed application website. Add an Android app hash for Google SMS Retriever, alongside iOS AutoFill and WebOTP support.

• The domain is never typed: `autofill_domain` is derived from the application's reviewed website (its registrable domain, so subdomains are covered) and is read-only in every response. `autofill_domain_enabled` switches its line on or off; `android_app_hash` (11 characters) is set per application, from the dashboard, or through the partner API on create and on the verify-settings patch.
• The `@domain #code` line adds about 25 characters. Arabic SMS is billed per 70-character segment, so the line can turn one segment into two: the console preview shows the segment count, and the switch exists for exactly that reason.
• The SMS gains, after the human-readable text: the Android app-hash line (when a hash is set and Android is targeted), then `@domain #code` as the very last line (when a domain is set and the web is targeted).
• iOS AutoFill and the WebOTP API read only the last line of the message, which is why the domain line always comes last, after the app hash.
• Google's SMS Retriever only needs the hash present anywhere in the message, and the whole message under 140 bytes. GSM-7 text is 1 byte per character; anything outside that alphabet (most Arabic) is 2 bytes per character.
• The optional `autofill` field on `start` (`web`, `android` or `none`) picks which line(s) go out on that one send; omit it to send every line the application has configured.
• The sandbox stamp, when present, always comes first, before any autofill line.
• Out of scope for WhatsApp: its message is a fixed Meta template with no room for either line.

Example message, under 140 bytes

Your Flower Shop verification code is: 482913
FA+9qCX9VSu
@shop.example.com #482913

Every error the API can return

Client webhooks

Configure a URL and a signing secret per application, and get a signed request for every outcome, with no polling.

• Configured per application on its Webhooks page: a URL and a secret, revealed on demand and rotatable. An application a partner provisioned has no webhook of its own: its verification outcomes go to the partner's event log and, when the partner subscribed to them, to the partner webhook, with the partner's `external_id`.
• `verification.verified` and `verification.failed` fire from `check`; `verification.expired` fires from the background expiry sweep, and from any `check` or `GET` that discovers the expiry itself.
• Every delivery carries `tawked-timestamp`, `tawked-signature` (hex HMAC-SHA256 of `"{timestamp}.{raw body}"` with your secret) and `tawked-event`. Verify the signature against the raw request body before trusting any payload.
• Delivery retries automatically with backoff on anything but a 2xx response, with the same job and schedule as partner webhooks; the exact retry count is below. The delivery log in the console shows every attempt.
• The URL must be https on a public host, and your endpoint must answer itself: a redirect is not followed and counts as a failed attempt.
• A test event sent from the console's Webhooks page is one sample `verification.verified` whose envelope also carries `"test": true`, with made-up values under `data`: an id of zeros, the reference `test-event`, the mode `test`. No real event carries `test`, so skip your own side effects when it is there.
• An application with WhatsApp also receives `message.sent`, `message.delivered`, `message.read` and `message.failed` at the same URL, in the same envelope (see WhatsApp messages).

{
    "event": "verification.verified",
    "data": {
        "id": "b7e5c2b0-9c1a-4e2f-8f2a-3a6b0e9d1c44",
        "status": "verified",
        "application_id": "c2a10f3e-8b7a-4d2e-9c1a-1a2b3c4d5e6f",
        "reference": "order-42",
        "channel": "sms",
        "to": "+966551234567",
        "mode": "live",
        "attempts": 1,
        "expires_at": "2026-09-01T12:34:56.789Z",
        "verified_at": "2026-09-01T12:31:02.145Z",
        "created_at": "2026-09-01T12:29:56.789Z"
    },
    "sent_at": "1788265862201"
}

const [timestamp, signature] = [
  req.headers["tawked-timestamp"],
  req.headers["tawked-signature"],
];
const expected = crypto
  .createHmac("sha256", webhookSecret)
  .update(`${timestamp}.${rawBody}`)
  .digest("hex");
if (!crypto.timingSafeEqual(Buffer.from(signature), Buffer.from(expected))) throw new Error("bad signature");

Retried on anything but a 2xx response, up to 5 attempts, backing off by minutes: 1, 5, 30, 120, 360.