Verify quickstart

By the end of this page your server sends a code to your phone and checks the code you type. It takes two requests and a test key, and you can do it while your application is still in review.

Hand this to your coding agent to wire Tawked Verify into your project.

Open in Cursor

Before you start

A Tawked account with an application that has Verify. Sign up if you have none.
The account owner’s phone at hand: a test key sends only to it.

Want to see it work before writing code? Open Verify → Test in the console. It sends a test code to the account owner’s phone, checks the code you type, and then shows the same two requests with your test key in them, ready to copy.

Create a test key

In the console, open your application, then Application settings → API keys. Choose Create a key, set Type to Test, and select Create test key. Copy the key (tk_test_...): it is shown in full only once.Put it in an environment variable on your server:

.env

TAWKED_KEY=tk_test_xxxxxxxxxxxxxxxxxxxx

A test key sends real SMS, but only to the phone the account owner verified at signup, stamped [TEST], and at most 10 times per application. Testing and the sandbox has the details.

Start a verification

Send a code to the owner’s phone. to takes any accepted Saudi mobile format, and lang picks the language of the SMS (Arabic unless it is exactly en).

curl -X POST https://tawked.com/v1/verify/start \
  -H "Authorization: Bearer $TAWKED_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "to": "0551234567", "lang": "ar" }'

const res = await fetch('https://tawked.com/v1/verify/start', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.TAWKED_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({ to: '0551234567', lang: 'ar' }),
});
const { id } = await res.json(); // keep the id for the check

use Illuminate\Support\Facades\Http;

$res = Http::withToken(env('TAWKED_KEY'))
    ->post('https://tawked.com/v1/verify/start', ['to' => '0551234567', 'lang' => 'ar']);
$id = $res->json('id'); // keep the id for the check

import os, requests

res = requests.post(
    "https://tawked.com/v1/verify/start",
    headers={"Authorization": f"Bearer {os.environ['TAWKED_KEY']}"},
    json={"to": "0551234567", "lang": "ar"},
)
verification_id = res.json()["id"]  # keep the id for the check

The answer is 201:

{
  "id": "b7e5c2b0-9c1a-4e2f-8f2a-3a6b0e9d1c44",
  "status": "pending",
  "expires_at": "2026-09-01T12:34:56.789Z"
}

id is what you check against, and expires_at is when the code stops working.If it does not start, the error string says why. The likely ones with a test key:

Answer	Why
`422 sandbox_unverified_destination`	`to` is not the account owner’s verified phone.
`422 invalid_destination`	`to` is not a Saudi mobile number in an accepted format.
`429 sandbox_quota_exceeded`	The application used its 10 test sends.

Every other code is on the Errors page.

Check the code

Post the id and the code you received. The code is compared exactly as sent: never trimmed, never normalised.

curl -X POST https://tawked.com/v1/verify/check \
  -H "Authorization: Bearer $TAWKED_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "id": "b7e5c2b0-9c1a-4e2f-8f2a-3a6b0e9d1c44", "code": "482913" }'

const res = await fetch('https://tawked.com/v1/verify/check', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.TAWKED_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({ id, code: '482913' }),
});
const { verified, status } = await res.json();

$res = Http::withToken(env('TAWKED_KEY'))
    ->post('https://tawked.com/v1/verify/check', ['id' => $id, 'code' => '482913']);
$verified = $res->json('verified');
$status = $res->json('status');

res = requests.post(
    "https://tawked.com/v1/verify/check",
    headers={"Authorization": f"Bearer {os.environ['TAWKED_KEY']}"},
    json={"id": verification_id, "code": "482913"},
)
verified = res.json()["verified"]
status = res.json()["status"]

Every outcome is a 200. Read verified first, then status for the reason:

{ "verified": true, "status": "verified" }

{ "verified": false, "status": "invalid_code", "attempts_remaining": 2 }

status is one of verified, invalid_code, too_many_attempts, failed, expired or canceled. An unknown id is the one exception: 404 { "error": "not_found" }. A verified request stays verified and ignores later codes.Build a sign-in flow shows what to tell the person for each outcome.

Go live

Once the application is approved, create a live key on the same API keys page and put it in TAWKED_KEY. The endpoints and shapes are the same. The [TEST] stamp goes, the sandbox limits no longer apply, and codes reach any Saudi mobile number.Until approval, a live key answers 403 account_not_active on codes. Before you switch, read Reliability and limits: an Idempotency-Key on every start, and client_ip for the protection guard.

Defaults you can tune

Each application has its own settings, under Verify → Settings. The defaults, and their bounds:

Setting	Default	Bounds
Code length	6 digits	4 to 8
Code lifetime	300 seconds	one of 60, 120, 180, 300, 600, 900
Wrong attempts allowed	3	1 to 5
Codes per number per hour	5	1 to 10
Resends per verification	3	fixed

What next

Build a sign-in flow

The number field, the code field, resends and what to tell the person.

Authentication

Key types, access by product, expiry and IP allowlists.

Reliability and limits

Idempotency keys, rate limits, retries and the protection guard.

Webhooks

Get told when a verification is verified, fails or expires.

Get started

Verify

Notifications

Email

Webhooks and errors

Partners

Build with AI

Verify quickstart

Defaults you can tune

What next

Build a sign-in flow

Authentication

Reliability and limits

Webhooks

​Defaults you can tune

​What next

Build a sign-in flow

Authentication

Reliability and limits

Webhooks

Defaults you can tune

What next