Applications

An application is what a merchant sends under: a reviewed brand (two names and a website), the verify settings, and the state that says whether it may send. You address it by your own external_id; Tawked’s application_id comes back in every response, but you never need to store it.

Idempotent writes

Every write on the partner API takes an Idempotency-Key header: 1 to 128 printable ASCII characters you generate, one per business event, scoped to your API key. Replaying it with the same request answers the original 2xx unchanged, with the response header Idempotent-Replayed: true, and runs nothing again: no second SMS to a merchant, no second application. The same key with a different request answers 409 idempotency_key_reused, and a request still in flight 409 idempotency_in_progress. A refused request is never stored, so fix it and retry under the same key. Keys expire after 24 hours.

curl -X POST https://tawked.com/v1/partner/applications/store_88/owner \
  -H "Authorization: Bearer tk_partner_xxxxxxxxxxxxxxxxxxxx" \
  -H "Idempotency-Key: store_88-owner-invite-1" \
  -H "Content-Type: application/json" \
  -d '{ "name": "أحمد", "phone": "0551234567" }'

Provisioning is idempotent on external_id even without the header; the header adds the guarantee that a retried call answers exactly what the first one did.

Provision

POST /v1/partner/applications creates the application, screens its names, and either queues it for review or activates it at once, according to your approval mode.

curl -X POST https://tawked.com/v1/partner/applications \
  -H "Authorization: Bearer tk_partner_xxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "external_id": "store_88",
    "name_ar": "متجر الورد",
    "name_en": "Flower Shop",
    "website": "https://flowers.example",
    "industry": "ecommerce",
    "merchant": { "registration_number": "1010123456", "contact_email": "owner@flowers.example" },
    "verify": { "code_length": 6, "ttl_seconds": 300 }
  }'

Field	Required	Notes
`external_id`	yes	Your own id for the merchant or store, 1 to 128 characters. Every later call uses it, and it is the `application` value on sends.
`name_ar`, `name_en`	yes	The brand names end users see in their messages, 1 to 80 characters each. Screened against protected brands and bait words.
`website`	yes	An `http` or `https` URL. The autofill domain is derived from it and is read-only. `website_url` is accepted as an alias.
`industry`	no	Free text up to 64 characters, `other` when omitted.
`merchant`	no	Your own record of the merchant, stored as given, never validated for shape.
`verify`	no	Initial verify settings, any subset of the fields below. Defaults for the rest.

The answer is 201 the first time and 200 when the external_id already exists. Both carry the application as it stands:

{
  "service_id": "c2a10f3e-8b7a-4d2e-9c1a-1a2b3c4d5e6f",
  "application_id": "c2a10f3e-8b7a-4d2e-9c1a-1a2b3c4d5e6f",
  "external_id": "store_88",
  "status": "review",
  "screening": { "result": "clean", "rules": [] },
  "verify": {
    "code_length": 6,
    "ttl_seconds": 300,
    "max_attempts": 3,
    "max_per_hour": 5,
    "autofill_domain": "flowers.example",
    "autofill_domain_enabled": true,
    "android_app_hash": null,
    "daily_spend_cap_halalas": null,
    "max_per_ip_per_hour": 20,
    "max_new_destinations_per_hour": 300
  },
  "paused": false
}

Provisioning is idempotent on external_id at the database level, so an install that runs twice, or two installs racing, end with one application. A repeat answers 200 with the current state and applies nothing from the new body, verify included. To change settings later, use the verify-settings endpoint.

A refused field answers 400 invalid_request with fields naming it in your own spelling, for example ["external_id", "website", "verify.code_length"].

Provision in bulk

POST /v1/partner/applications/batch takes up to 100 provisioning bodies in one call, for a migration or a nightly sync:

curl -X POST https://tawked.com/v1/partner/applications/batch \
  -H "Authorization: Bearer tk_partner_xxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: sync-2026-09-27" \
  -d '{
    "applications": [
      { "external_id": "store_88", "name_ar": "متجر الورد", "name_en": "Flower Shop", "website": "https://flowers.example" },
      { "external_id": "store_89", "name_ar": "مخبز السنابل", "name_en": "Sanabel Bakery", "website": "https://sanabel.example" }
    ]
  }'

Each item is exactly the body of a single provision. Items run in order, one at a time, each in its own transaction and with its own events. The answer is always 200 with the counts and one result per item, in the same order:

{
  "created": 1,
  "existing": 1,
  "refused": 0,
  "results": [
    { "index": 0, "external_id": "store_88", "outcome": "existing", "application": { "service_id": "c2a10f3e-8b7a-4d2e-9c1a-1a2b3c4d5e6f", "application_id": "c2a10f3e-8b7a-4d2e-9c1a-1a2b3c4d5e6f", "external_id": "store_88", "status": "active", "screening": { "result": "clean", "rules": [] }, "verify": { "code_length": 6, "ttl_seconds": 300, "max_attempts": 3, "max_per_hour": 5, "autofill_domain": "flowers.example", "autofill_domain_enabled": true, "android_app_hash": null, "daily_spend_cap_halalas": null, "max_per_ip_per_hour": 20, "max_new_destinations_per_hour": 300 }, "paused": false } },
    { "index": 1, "external_id": "store_89", "outcome": "created", "application": { "service_id": "9d1c2b3a-4e5f-4a6b-8c7d-0e1f2a3b4c5d", "application_id": "9d1c2b3a-4e5f-4a6b-8c7d-0e1f2a3b4c5d", "external_id": "store_89", "status": "review", "screening": { "result": "clean", "rules": [] }, "verify": { "code_length": 6, "ttl_seconds": 300, "max_attempts": 3, "max_per_hour": 5, "autofill_domain": "sanabel.example", "autofill_domain_enabled": true, "android_app_hash": null, "daily_spend_cap_halalas": null, "max_per_ip_per_hour": 20, "max_new_destinations_per_hour": 300 }, "paused": false } }
  ]
}

outcome is created (screened, then queued or activated like a single provision), existing (the external_id was already yours: the current state, nothing applied from the item) or refused (fields names the refused fields as a single provision would, application is null, and the rest of the batch still runs).
The same external_id twice in one batch is created then existing.
applications must be a list of 1 to 100 objects; anything else answers 400 invalid_request with fields: ["applications"]. An item that is not an object is refused with fields: ["item"].
Send an Idempotency-Key: a replay answers the same envelope and provisions nothing again.
Every created application fires its own events and enters your review queue as usual, so a batch of a hundred under a manual approval mode is a hundred reviews.

What happens after provisioning

Both names are screened against protected brands, bait words and structural rules (a URL, a phone number or an email inside a name). The verdict comes back as screening.result, clean or flagged, with the rules that fired: protected_brand: followed by the category and the term, bait_word: followed by the word, or structural:url, structural:phone, structural:email, structural:too_short, structural:too_long, structural:bidi_or_invisible, structural:control_chars. What happens next depends on the approval mode Tawked set on your account:

Approval mode	Clean names	Flagged names
Tawked reviews everything	Tawked	Tawked
You approve clean names	You, in the console’s Reviews queue	Tawked
You approve everything	You	You
Auto-clean	Active at once, no human at all	Tawked

There is no approve or reject endpoint. Under auto-clean nothing decides a clean name at all; otherwise the decision is made in a console, yours when your mode allows it and Tawked’s when it does not. Your backend learns the outcome from the service.approved and service.rejected webhooks, or by reading the application.

`status`	Meaning	Codes	WhatsApp
`review`	Waiting for a decision.	`403 account_not_active`	Allowed: review gates codes only.
`active`	Approved.	Allowed	Allowed
`rejected`	Refused, with a reason in the webhook. Fix the brand with a PATCH to resubmit.	`403 account_not_active`	`403 account_not_active`
`suspended`	Suspended by Tawked. Contact support.	`403 account_not_active`	`403 account_not_active`

Two more switches live beside status and never change it:

Field	Set by	Codes	WhatsApp
`disabled: true`	You, with suspend; cleared with resume.	`403 account_not_active`	`403 account_not_active`
`paused: true`	The protection guard, after a spike in new destinations; cleared with unpause.	`403 application_paused`	Allowed: the guard watches codes.

List and read

GET /v1/partner/applications lists your applications newest first, with status, disabled (true or false), limit (1 to 100) and offset as query parameters; total counts the matches before paging. GET /v1/partner/applications/{external_id} reads one. Both print the same row: the fields above plus name_ar, name_en, disabled and created_at.

curl "https://tawked.com/v1/partner/applications?status=review&limit=50" \
  -H "Authorization: Bearer tk_partner_xxxxxxxxxxxxxxxxxxxx"

An external_id that is not yours answers 404 not_found, whether or not it exists under another partner.

What a row carries

Field	Meaning
`service_id`, `application_id`	Tawked’s id, twice (the first is the legacy name).
`external_id`	Yours.
`status`, `status_message`	`review`, `active`, `rejected` or `suspended`, and the reason Tawked or you gave on a rejection or a suspension.
`screening`	The verdict on the names: `result` and the rules that fired.
`verify`	The verify settings in force.
`paused`, `paused_at`, `pause_reason`	The protection guard’s pause, when it landed and why (`destination_spike`).
`disabled`, `disabled_at`	Your own switch and when you flipped it.
`archived`, `archived_at`	Whether you archived it, and when.
`approved_at`	When the application was last approved, `null` while it waits or after a rejection.
`name_ar`, `name_en`, `website`, `industry`, `merchant`, `logo_url`	The brand as you sent it, plus the logo you uploaded.
`metadata`	Your own tags, or `null`.
`owner`	`status` (`none`, `invited`, `accepted`), the person’s `name` and `phone`, `invited_at`, `expires_at`, `accepted_at`. The same states as the owner endpoint, without the email.
`whatsapp`	`enabled`, and the `number` when one is attached: `phone`, `verified_name`, `connected`, `health` (`pending`, `healthy`, `degraded`, `blocked`, `disconnected`) and `stage` (`setting_up`, `action_needed`, `add_payment`, `meta_reviewing`, `limited`, `ready`).
`created_at`	When you provisioned it.

Metadata

metadata is yours: up to 20 string values of at most 200 characters, under keys of 1 to 40 lowercase letters, digits and underscores. Send it on provision or on a brand update; it is replaced whole when present, unchanged when omitted, and cleared by null or {}. Tawked never reads it and it is not a brand change, so it never sends an application back to review. A refused key comes back in fields as metadata. followed by the key.

curl -X PATCH https://tawked.com/v1/partner/applications/store_88 \
  -H "Authorization: Bearer tk_partner_xxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{ "name_ar": "متجر الورد", "name_en": "Flower Shop", "website": "https://flowers.example", "metadata": { "plan": "pro", "region": "riyadh" } }'

The list filters by containment: GET /v1/partner/applications?metadata[plan]=pro&metadata[region]=riyadh returns the applications whose metadata holds every pair.

Logo

POST /v1/partner/applications/{external_id}/logo takes a multipart upload in the field logo: a PNG or a JPEG of at most 256 KB, recognised by its bytes and never by its name. It is stored where the console stores it and comes back as logo_url on every row. A new logo is a brand change, so an active application returns to review until it is approved again, exactly like a renamed one. DELETE .../logo drops it without a review.

curl -X POST https://tawked.com/v1/partner/applications/store_88/logo \
  -H "Authorization: Bearer tk_partner_xxxxxxxxxxxxxxxxxxxx" \
  -F "logo=@logo.png"

History

GET /v1/partner/applications/{external_id}/history is the review history the console shows, newest first: provisioned, submitted, approve, reject, suspend, resume, brand_changed, settings_changed, renamed, each with actor (partner, tawked, system or client, never a person), reason and the screening verdict at that moment.

{
  "external_id": "store_88",
  "events": [
    { "action": "approve", "actor": "partner", "reason": null, "screening": { "result": "clean", "rules": [] }, "created_at": "2026-09-02T09:00:00.000Z" },
    { "action": "provisioned", "actor": "system", "reason": null, "screening": { "result": "clean", "rules": [] }, "created_at": "2026-09-01T12:00:00.000Z" }
  ]
}

Screening preview

POST /v1/partner/screening with name_ar and name_en answers the verdict the names would get and what would happen next under your approval mode, without creating anything: review.needed says whether a provision would wait for a decision, review.decided_by whether that decision is yours (partner) or Tawked’s. Warn the merchant at signup instead of after.

{ "result": "flagged", "rules": ["protected_brand:banks:alrajhi"], "review": { "needed": true, "decided_by": "tawked" } }

Update the brand

PATCH /v1/partner/applications/{external_id} replaces the brand in full: name_ar, name_en and website are required on every call, industry, merchant and verify are optional. The names are screened again. A change to a name or the website returns an active application to review until it is approved again, and codes refuse meanwhile (WhatsApp sends are not held back by review); a call that changes none of the three keeps the status, so a nightly sync that sends the same brand is harmless.

curl -X PATCH https://tawked.com/v1/partner/applications/store_88 \
  -H "Authorization: Bearer tk_partner_xxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{ "name_ar": "متجر الورد الجديد", "name_en": "New Flower Shop", "website": "https://flowers.example" }'

The answer is the same body as provisioning, with the new status and screening.

Verify settings

PATCH /v1/partner/applications/{external_id}/verify-settings changes any subset of the settings. Send the fields at the top level or nested under verify; omitted fields stay as they are. A value out of range refuses the whole request with the offending names in fields, nothing is clamped or half-applied, and an empty or unrecognised patch is refused with fields: ["verify"]. Nothing here re-screens the names or changes the status.

curl -X PATCH https://tawked.com/v1/partner/applications/store_88/verify-settings \
  -H "Authorization: Bearer tk_partner_xxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{ "code_length": 8, "ttl_seconds": 600, "android_app_hash": "FA+9qCX9VSu" }'

Field	Default	Bounds	What it does
`code_length`	6	4 to 8	Digits in the code.
`ttl_seconds`	300	one of 60, 120, 180, 300, 600, 900	How long a code lives, in seconds.
`max_attempts`	3	1 to 5	Wrong codes allowed per verification.
`max_per_hour`	5	1 to 10	Sends to one destination per hour.
`autofill_domain_enabled`	`true`	boolean	Whether the `@domain #code` line goes out at the end of the SMS.
`android_app_hash`	`null`	11 characters, or `null` to clear	The hash for Google’s SMS Retriever on Android.
`daily_spend_cap_halalas`	`null` (off)	100 to 100000000, or `null`	A cap on one day’s charges (Riyadh calendar day). Over it, sends answer `429 spend_cap_reached`.
`max_per_ip_per_hour`	20	1 to 1000	Starts per end-user IP per hour, when you pass `client_ip`. Over it, that address answers `429 ip_rate_limited`.
`max_new_destinations_per_hour`	300	10 to 100000	Distinct new destinations per hour. Crossing it pauses the application.

autofill_domain is read-only: it is derived from the website (its registrable domain) and comes back in every response. Destinations and messages explains what the lines do. The answer is every setting in force after the change:

{
  "external_id": "store_88",
  "verify": {
    "code_length": 8,
    "ttl_seconds": 600,
    "max_attempts": 3,
    "max_per_hour": 5,
    "autofill_domain": "flowers.example",
    "autofill_domain_enabled": true,
    "android_app_hash": "FA+9qCX9VSu",
    "daily_spend_cap_halalas": null,
    "max_per_ip_per_hour": 20,
    "max_new_destinations_per_hour": 300
  }
}

Suspend, resume and unpause

Suspend is your own off switch, for a merchant that left your platform or stopped paying you: every send answers 403 account_not_active until you resume. The review status is untouched, so an application approved before comes back sending at once, and suspending fires service.suspended. Both answer { "external_id": "store_88", "disabled": true } or false, and both are safe to repeat. Unpause is different: it lifts an automatic pause by the protection guard after a spike in distinct new destinations within an hour, announced by service.paused and visible as paused: true. Codes answer 403 application_paused meanwhile. Look at what the merchant was doing before you unpause; the guard exists to stop SMS pumping within seconds.

Archive and restore

POST /v1/partner/applications/{external_id}/archive is your delete, and it is reversible. An archived application leaves the list, the counts and the review queues, every send answers 403 account_not_active, and every other write answers 409 application_archived; the history, the usage and the ledger stay, and GET .../{external_id} still reads it with archived: true and archived_at. The list shows archived applications only when asked: GET /v1/partner/applications?archived=true. Two things must be gone first: a WhatsApp number in any state (409 number_connected, the inbox belongs to the team that runs it) and an owner (409 owner_assigned, revoke first). A pending invitation is withdrawn by the archive itself. Archiving fires service.archived. POST .../restore brings it back exactly as it was: the status, your switch, the pause and the settings are untouched, and service.restored fires. A merchant that installs again restores it too: provisioning an archived external_id answers 200 with the application restored, since provisioning is idempotent on the id. Both calls answer the same when there is nothing to do.

curl -X POST https://tawked.com/v1/partner/applications/store_88/archive \
  -H "Authorization: Bearer tk_partner_xxxxxxxxxxxxxxxxxxxx" \
  -H "Idempotency-Key: store_88-archive-1"

There is no delete beyond this: an archived application keeps its external_id.

Usage

GET /v1/partner/usage reports, per application and over a window, the codes that went out (sent, whatever their outcome), the ones confirmed (verified) and the charges net of refunds (spend_halalas), plus your current balance. from and to are ISO 8601; to defaults to now and from to 30 days before it. Applications with no activity in the window are left out, rows are sorted by sent, and there is no paging.

curl "https://tawked.com/v1/partner/usage?from=2026-08-01&to=2026-08-31" \
  -H "Authorization: Bearer tk_partner_xxxxxxxxxxxxxxxxxxxx"

{
  "from": "2026-08-01T00:00:00.000Z",
  "to": "2026-08-31T00:00:00.000Z",
  "balance_halalas": 123456,
  "applications": [
    { "external_id": "store_88", "application_id": "c2a10f3e-8b7a-4d2e-9c1a-1a2b3c4d5e6f", "name_ar": "متجر الورد", "sent": 41, "verified": 33, "spend_halalas": 369 }
  ]
}

The same report is a CSV in the partner console under Usage.

Get started

Verify

WhatsApp

Partners

For agents

Idempotent writes

Provision

Provision in bulk

What happens after provisioning

List and read

What a row carries

Metadata

Logo

History

Screening preview

Update the brand

Verify settings

Suspend, resume and unpause

Archive and restore

Usage

​Idempotent writes

​Provision

​Provision in bulk

​What happens after provisioning

​List and read

​What a row carries

​Metadata

​Logo

​History

​Screening preview

​Update the brand

​Verify settings

​Suspend, resume and unpause

​Archive and restore

​Usage

Idempotent writes

Provision

Provision in bulk

What happens after provisioning

List and read

What a row carries

Metadata

Logo

History

Screening preview

Update the brand

Verify settings

Suspend, resume and unpause

Archive and restore

Usage