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
}
}'const res = await fetch("https://tawked.com/v1/partner/applications", {
method: "POST",
headers: {
Authorization: "Bearer tk_partner_xxxxxxxxxxxxxxxxxxxx",
"Content-Type": "application/json",
},
body: JSON.stringify({
"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
}
}),
});
const data = await res.json();<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://tawked.com/v1/partner/applications",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'external_id' => '<string>',
'name_ar' => '<string>',
'name_en' => '<string>',
'website' => '<string>',
'industry' => '<string>',
'merchant' => [
],
'verify' => [
],
'metadata' => [
]
]),
CURLOPT_HTTPHEADER => [
"Authorization: Bearer <token>",
"Content-Type: application/json"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}import requests
res = requests.post(
"https://tawked.com/v1/partner/applications",
headers={"Authorization": "Bearer tk_partner_xxxxxxxxxxxxxxxxxxxx"},
json={
"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
}
},
)
data = res.json(){
"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
}Provision an application
Creates an application for one of your merchants under your own id for it, screens its names, and either queues it for review or activates it at once, according to your approval mode. Idempotent on external_id: provisioning the same id again answers 200 with the application as it stands and applies nothing from the new body, so an install that runs twice is safe.
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
}
}'const res = await fetch("https://tawked.com/v1/partner/applications", {
method: "POST",
headers: {
Authorization: "Bearer tk_partner_xxxxxxxxxxxxxxxxxxxx",
"Content-Type": "application/json",
},
body: JSON.stringify({
"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
}
}),
});
const data = await res.json();<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://tawked.com/v1/partner/applications",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'external_id' => '<string>',
'name_ar' => '<string>',
'name_en' => '<string>',
'website' => '<string>',
'industry' => '<string>',
'merchant' => [
],
'verify' => [
],
'metadata' => [
]
]),
CURLOPT_HTTPHEADER => [
"Authorization: Bearer <token>",
"Content-Type: application/json"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}import requests
res = requests.post(
"https://tawked.com/v1/partner/applications",
headers={"Authorization": "Bearer tk_partner_xxxxxxxxxxxxxxxxxxxx"},
json={
"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
}
},
)
data = res.json(){
"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
}Authorizations
Authorization: Bearer . An application key (tk_live_, tk_test_) has full access, which covers every product and any product added later, or custom access, chosen when the key is created: one or more of the scopes verify:check, verify:send (includes verify:check), notifications:read, notifications:send (includes notifications:read), email:read, email:send (includes email:read), email:manage (includes email:send), webhooks:manage, email:inbound, notifications:templates (includes notifications:read), chat:menus, chat:attendant. No key made on the API keys page holds notifications:templates, full access included: the three template writes answer such a key 403 insufficient_scope. A connected app's key holds it. Nor chat:menus: the five conversation menu operations answer such a key 403 insufficient_scope, and a connected app's key holds it once the client approved it. Nor chat:attendant: the five auto-attendant operations answer such a key 403 insufficient_scope too, and a connected app's key holds it once the client approved it. email:manage and webhooks:manage are held only by a key someone chose them for: a full-access key, old or new, never holds them. email:inbound, which reads, deletes and forwards received e-mail, is opt-in on every key, full access included: a key holds it only when it was turned on when the key was created. A call outside the key's access answers 403 insufficient_scope and names the scope it needs in the WWW-Authenticate response header. A partner key (tk_partner_) always has full access. Whatever its access, a key is a server-side secret.
Headers
A 1 to 128 printable-ASCII key you generate, 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; the same key with another request answers 409 idempotency_key_reused, and a request still in flight 409 idempotency_in_progress. A refused request is never stored, so a corrected retry under the same key runs. Keys expire after 24 hours.
Body
Your own id for the merchant or store, 1 to 128 characters after trimming. Every later call addresses the application by it, and it is the application value on the Verify endpoints.
The Arabic brand name end users see in their messages, 1 to 80 characters. Screened against protected brands and bait words.
The English brand name, 1 to 80 characters. Screened like name_ar.
The merchant's website, an http or https URL. The autofill domain is derived from it (its registrable domain) and is read-only; website_url is accepted as an alias.
Free text up to 64 characters, other when omitted. The client console uses ecommerce, fintech, healthcare, education, logistics, saas, marketplace and other.
Your own record of the merchant (a registration number, a contact, a KYC state), stored with the application exactly as given and never validated for shape.
Initial verify settings: any subset of the fields of the verify-settings endpoint, the defaults for the rest. A refused value is reported in fields as verify. followed by the field name. Ignored when the application already exists.
Your own tags on the application: up to 20 string values of at most 200 characters under keys of 1 to 40 lowercase letters, digits and underscores. Replaced whole when present, unchanged when omitted, cleared by null or {}; never read by Tawked and not a brand change. A refused key is reported in fields as metadata. followed by the key. The list filters by it.