> ## Documentation Index
> Fetch the complete documentation index at: https://docs.tawked.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Partner API
> One account, one key, an application per merchant: provision, send on their behalf, hand over to the owner, and get told by webhook.
A partner is a platform or an agency that runs Tawked for its merchants: a marketplace app, an e-commerce platform, an agency building for several brands. Tawked never creates an account, a wallet or a key for the merchant. The partner holds one account with one prepaid balance at its negotiated price, one `tk_partner_` key that covers every application, and an application per merchant addressed by the partner's own id for it, the `external_id`. The merchant does not need to know Tawked exists until the day it wants WhatsApp, and then the partner hands the application over.
Provision one per merchant, keep its brand and verify settings current, switch it off and on, read usage.
The `application` field on every Verify and WhatsApp call, and what blocks a send.
Hand an application to the merchant so they connect their own WhatsApp number and run the inbox.
Every event, which ones reach your webhook, and the feed to poll or catch up from.
The envelope, the signature, the retries, and the delivery log by API.
## Who holds what
| | Partner | Merchant (owner) |
| --------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------- |
| Balance and price | Pays every send from its prepaid balance, at the partner's price. | Nothing. Billing never moves. |
| Keys and webhooks | The `tk_partner_` key and the partner webhook. | Never sees them. |
| Brand and review | Provisions, edits the brand, sees the screening verdict, decides in its Reviews queue within its approval mode. | Reads the brand. |
| Verify settings | Sets them through the API or the console. | Reads them. |
| Sending codes and messages | Through the API, naming the application. | Not through the API. |
| WhatsApp number, templates, inbox | Connects a number for its own applications from the partner console. After a handover: reads the number's state and the message log, manages templates and the agents on the team. | Connects its own WhatsApp Business number, runs the inbox with its team, manages templates. |
## The lifecycle of an application
```
POST /v1/partner/applications ──▶ screening ──▶ review ──▶ active ──▶ sending
│ │
│ └──▶ rejected (fix the brand with PATCH to resubmit)
└──▶ active at once (auto-clean mode, clean names)
Your switch: suspend ⇄ resume disabled: true | false, status untouched
The guard: paused ──▶ unpause a spike in new destinations, status untouched
Tawked: suspended a status; contact support
Handover: none ──▶ invited ──▶ accepted (revoke at any point while no number is connected)
Archive: archive ⇄ restore your delete, reversible; refused with a number or an owner; re-provisioning restores
```
## Getting started
Partner accounts are opened by Tawked, not by signup. Write to [support@tawked.com](mailto:support@tawked.com) with what you run and how many merchants you expect. You sign in with your phone like any account and land in the partner console.
Partner console, **Integration**, **API key**. The key is shown once; you can give it an expiry and an IP allowlist, and it is always full scope. Rotating issues the new key and revokes the old one in the same step, with no overlap window, so rotate from where you can update the secret at once.
**Integration**, **Webhook**: an HTTPS URL, a signing secret revealed on demand and rotatable, and a low-balance threshold in halalas. See [Partner webhooks](/partners/webhooks).
[`POST /v1/partner/applications`](/api-reference/partner/provision-an-application) with your `external_id`, the Arabic and English brand names and the website. The answer says whether the application is `active` already or in `review`; `service.approved` or `service.rejected` tells your backend the outcome.
Every Verify and WhatsApp call takes `application` with your `external_id`. See [Sending for an application](/partners/sending).
[`POST /v1/partner/applications/{external_id}/owner`](/api-reference/partner/invite-the-owner) invites the merchant by phone. See [Application owners](/partners/owners).
## Start with the profile
[`GET /v1/partner/profile`](/api-reference/partner/get-the-profile) says who the key belongs to and what to expect: the approval mode (whether a provision waits for a human, and whose decision it is), the price of a code and of a WhatsApp message for your account, the balance, the rate limit, the owner-invitation caps, the key in use with its expiry and allowlist, and whether a webhook is configured. An agent reads it before its first provision.
## The shape of the partner API
| | |
| -------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Base URL | `https://tawked.com` (`/api/v1/...` answers too) |
| Authentication | `Authorization: Bearer tk_partner_...` or `x-api-key`. `tk_partner_test_...` is the [sandbox key](/partners/sending#the-sandbox-key): it reads and sends, and every write answers `403 live_key_required`. A `tk_live_` or `tk_test_` key answers `401 unauthorized` here. |
| Addressing | Every application by your `external_id`, never by a Tawked id. |
| Idempotency | An `Idempotency-Key` header on every write. A replay answers the original response with `Idempotent-Replayed: true`. See [Idempotent writes](/partners/applications#idempotent-writes). |
| Rate limit | 120 requests per minute per key, sends and partner calls together. |
| Legacy names | `/v1/partner/services` answers exactly like `/v1/partner/applications`, with `services` as the collection key; `service_id` in every body is the old name of `application_id`. Use `applications` in new code. |
| Request id | Every response carries `X-Request-Id`. Quote it when you contact support. |
The full reference, each page with a playground: [Get the profile](/api-reference/partner/get-the-profile), [Preview the screening](/api-reference/partner/preview-the-screening), [Provision an application](/api-reference/partner/provision-an-application), [Provision in bulk](/api-reference/partner/provision-in-bulk), [List applications](/api-reference/partner/list-applications), [Get an application](/api-reference/partner/get-an-application), [Get the history](/api-reference/partner/get-the-history), [Update the brand](/api-reference/partner/update-the-brand), [Upload the logo](/api-reference/partner/upload-the-logo), [Remove the logo](/api-reference/partner/remove-the-logo), [Update the verify settings](/api-reference/partner/update-the-verify-settings), [Suspend](/api-reference/partner/suspend-an-application), [Resume](/api-reference/partner/resume-an-application), [Unpause](/api-reference/partner/unpause-an-application), [Archive](/api-reference/partner/archive-an-application), [Restore](/api-reference/partner/restore-an-application), [Get the owner](/api-reference/partner/get-the-owner), [Invite the owner](/api-reference/partner/invite-the-owner), [Revoke the owner](/api-reference/partner/revoke-the-owner), [Get usage](/api-reference/partner/get-usage), [List verifications](/api-reference/partner/list-verifications), [List WhatsApp messages](/api-reference/partner/list-whatsapp-messages), [Get the event feed](/api-reference/partner/get-the-event-feed), [Get the webhook](/api-reference/partner/get-the-webhook), [Update the webhook](/api-reference/partner/update-the-webhook), [List deliveries](/api-reference/partner/list-deliveries), [Retry a delivery](/api-reference/partner/retry-a-delivery), [Get the WhatsApp state](/api-reference/partner/get-the-whatsapp-state), [List the templates](/api-reference/partner/list-the-templates), [Get a template](/api-reference/partner/get-a-template), [Create a template](/api-reference/partner/create-a-template), [Update a template](/api-reference/partner/update-a-template), [Delete a template](/api-reference/partner/delete-a-template), [List the team](/api-reference/partner/list-the-team), [Add a team member](/api-reference/partner/add-a-team-member), [Remove a team member](/api-reference/partner/remove-a-team-member).
To try the flow before anything is approved, create a sandbox key (`tk_partner_test_`) under **Integration**: provision a test merchant with the live key, then send with the sandbox key to your own verified phone, stamped and capped. See [The sandbox key](/partners/sending#the-sandbox-key).