Sending codes for an application

A partner key is account-level, so every Verify call says which application it is for. Everything else about those endpoints is exactly as the Quickstart describes: same shapes, same statuses, same errors, plus the ones below. A client application is Verify only: it sends one-time codes, never WhatsApp messages.

The `application` field

Pass your external_id as application:

in the JSON body of POST /v1/verify/start, POST /v1/verify/check, POST /v1/verify/{id}/resend and POST /v1/verify/{id}/cancel;
as a query parameter, ?application=store_88, on GET /v1/verify/{id}, since a GET has no body.

The legacy name service is accepted identically everywhere. A key can only check, read, resend or cancel a verification started under the same application; another application’s id answers 404 not_found.

curl -X POST https://tawked.com/v1/verify/start \
  -H "Authorization: Bearer tk_partner_xxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: order-42-otp-1" \
  -d '{ "to": "0551234567", "lang": "ar", "application": "store_88", "reference": "order-42", "client_ip": "203.0.113.7" }'

const res = await fetch('https://tawked.com/v1/verify/start', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.TAWKED_PARTNER_KEY}`,
    'Content-Type': 'application/json',
    'Idempotency-Key': 'order-42-otp-1',
  },
  body: JSON.stringify({ to: '0551234567', lang: 'ar', application: 'store_88', reference: 'order-42', client_ip: '203.0.113.7' }),
});
const { id } = await res.json();

use Illuminate\Support\Facades\Http;

$res = Http::withToken(env('TAWKED_PARTNER_KEY'))
    ->withHeaders(['Idempotency-Key' => 'order-42-otp-1'])
    ->post('https://tawked.com/v1/verify/start', [
        'to' => '0551234567',
        'lang' => 'ar',
        'application' => 'store_88',
        'reference' => 'order-42',
        'client_ip' => '203.0.113.7',
    ]);
$id = $res->json('id');

import os, requests

res = requests.post(
    "https://tawked.com/v1/verify/start",
    headers={"Authorization": f"Bearer {os.environ['TAWKED_PARTNER_KEY']}", "Idempotency-Key": "order-42-otp-1"},
    json={"to": "0551234567", "lang": "ar", "application": "store_88", "reference": "order-42", "client_ip": "203.0.113.7"},
)
verification_id = res.json()["id"]

Then check with the same application:

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

The message carries the application’s reviewed brand, never anything from the request, and the code is charged to your balance at your price. An Idempotency-Key is scoped to your key and the application together, so the same key under two applications is two sends.

What blocks a send

Checked in this order, before the endpoint’s own logic. The first three are the partner-key branch of the shared ladder on the Errors page.

HTTP	`error`	Cause	What to do
401	`unauthorized`	Bad key, or your partner account is suspended.	Check the key; contact support if the account was suspended.
400	`service_required`	No `application` (or `service`) in the request.	Pass it.
404	`service_not_found`	`application` is not one of your `external_id` values.	Provision it first, or fix the id.
403	`account_not_active`	The application is in `review`, `rejected` or `suspended`, you suspended it (`disabled: true`), it is archived, or your account is banned. All look the same here.	Read the application: `status`, `disabled` and `archived` say which.
403	`application_paused`	The protection guard paused it (`paused: true`).	Look at the traffic, then unpause.

Everything after that is the ordinary ladder on the Errors page: request shape, channel and destination, the per-destination hourly cap, the guard, your balance (402 insufficient_credits is your balance, not the merchant’s), then the send itself. A partner key always has full access, so 403 insufficient_scope on the shared ladder never answers it.

Reading what was sent

GET /v1/partner/verifications lists the codes your key sent across every client application, newest first. Each row is the public shape of GET /v1/verify/{id} plus application_id and your external_id, the key mode it was sent under (partner for your key), the lang and the price_halalas it was charged at.

curl "https://tawked.com/v1/partner/verifications?application=store_88&status=verified&from=2026-09-01&limit=50" \
  -H "Authorization: Bearer tk_partner_xxxxxxxxxxxxxxxxxxxx"

{
  "data": [
    {
      "id": "b7e5c2b0-9c1a-4e2f-8f2a-3a6b0e9d1c44",
      "application_id": "c2a10f3e-8b7a-4d2e-9c1a-1a2b3c4d5e6f",
      "external_id": "store_88",
      "status": "verified",
      "channel": "sms",
      "to": "+966551234567",
      "reference": "order-42",
      "attempts_remaining": 0,
      "resends_remaining": 0,
      "expires_at": "2026-09-26T12:34:56.789Z",
      "verified_at": "2026-09-26T12:31:02.145Z",
      "created_at": "2026-09-26T12:29:56.789Z",
      "mode": "partner",
      "lang": "ar",
      "price_halalas": 9
    }
  ],
  "next_cursor": "eyJ0IjoiMjAyNi0wOS0yNiAxMjoyOTo1Ni4wMDAwMDAiLCJpZCI6ImI3ZTVjMmIwLTljMWEtNGUyZi04ZjJhLTNhNmIwZTlkMWM0NCJ9",
  "has_more": false
}

Filters. application (your external_id; one that is not yours answers 404 not_found), reference (exact), from and to (ISO 8601, on created_at), status (pending, verified, failed, expired, canceled, read by the clock like GET /v1/verify/{id}) and mode. A value outside the vocabulary answers 400 invalid_request with the field named.
Paging. Keyset, no totals: limit is 1 to 100 (50 when omitted), next_cursor points after the last row you received whether or not more rows exist now, and has_more says whether another page is waiting. Pass it back as cursor; an empty page answers null. Rows created in the same second are ordered by id, so a cursor never skips or repeats one.
Archived applications keep their rows, with their external_id.

For sums rather than rows, GET /v1/partner/usage reports codes sent, verified codes and spend per application over a window.

Rate limit

The per-key limit of 120 requests per minute counts every call your key makes, codes and partner-API calls together. Spread bursts across a minute, or ask support for a higher limit.

The sandbox key

A partner sandbox key (tk_partner_test_..., created in the console under Clients → API and webhook, Sandbox key) is the same account and the same endpoints with the sandbox limits, so the code you write against it is the code you ship:

One destination. Sends reach only the phone the partner account’s owner verified at signup (the Sandbox key card shows it). Anything else answers 422 sandbox_unverified_destination.
A visible stamp. Every message carries the [TEST] / [تجريبي] stamp, and is charged like a live send.
Daily caps instead of the lifetime one: 20 sends per application and 200 per account a day (Riyadh time), answering 429 sandbox_quota_exceeded.
Applications in review can send, so a merchant can be tested before it is approved; rejected, suspended, disabled and archived ones cannot (403 account_not_active).
Reads work, writes do not. Every partner management write (provisioning, updates, suspend, archive, the webhook, retries) answers 403 live_key_required with the sandbox key, so a key that leaks into a test runner can change nothing. Provision test merchants with the live key, then send with the sandbox key.

The logs show these sends with mode: "partner_test", and GET /v1/partner/profile answers key.mode accordingly. One sandbox key is active at a time; rotating it revokes the old one at once.

Your own applications

Your account’s own applications are not sent for with the partner key: they are managed in the console like any other account’s, with Verify, Notifications and Chat, and send with their own keys (Application settings → API keys on the application). The WhatsApp number and its templates are under the application’s Notifications, and the inbox under Chat. See the Verify quickstart and Tawked Notifications.

Get started

Verify

Notifications

Email

Webhooks and errors

Partners

Build with AI

Sending codes for an application

The `application` field

What blocks a send

Reading what was sent

Rate limit

The sandbox key

Your own applications

​The application field

​What blocks a send

​Reading what was sent

​Rate limit

​The sandbox key

​Your own applications

The `application` field

What blocks a send

Reading what was sent

Rate limit

The sandbox key

Your own applications