Common workflows
Businesses
Register each of your customers once, by your own ID.
In a nutshell
A business is one customer of your product - a school, a shop. Create it with POST /businesses using your own external_id, and use that ID in every URL afterwards.
Your ID, not ours
A business is addressed by your external_id in every URL:
/api/v1/businesses/{external_id}/...
For Multi-SKUUL it is the tenant ID; for PaalPOS it could be the shop ID. PaalChat
never needs to know your database schema. Two products may use the same
external_id without clashing - a product only ever sees its own businesses.
external_id rules: 1-191 characters from A-Z a-z 0-9 . _ : -.
Create or update
POST /businesses creates the business, or updates it when the
external_id already exists. Call it when a customer signs up and whenever their
name or contact details change. It is safe to repeat.
curl -X POST https://whatsapp.paaltech.org/api/v1/businesses \
-H "Authorization: Bearer $PAALCHAT_TOKEN" -H "Accept: application/json" -H "Content-Type: application/json" \
-d '{"external_id": "st-augustines", "name": "St. Augustine'\''s College", "email": "info@augustines.edu.gh"}'
$business = Http::withToken(config('services.paalchat.token'))->acceptJson()
->post('https://whatsapp.paaltech.org/api/v1/businesses', [
'external_id' => $school->tenant_id,
'name' => $school->name,
'email' => $school->email,
])->throw()->json('data');
const { data: business } = await (await fetch(`${BASE}/businesses`, {
method: 'POST', headers: HEADERS,
body: JSON.stringify({ external_id: shop.id, name: shop.name, email: shop.email }),
})).json();
business = requests.post(f"{BASE}/businesses", headers=HEADERS,
json={"external_id": shop.id, "name": shop.name, "email": shop.email}).json()["data"]
201 when created, 200 when updated:
{
"data": {
"external_id": "st-augustines",
"name": "St. Augustine's College",
"email": "info@augustines.edu.gh",
"phone": null,
"status": "active",
"whatsapp": {"status": "not_connected", "wabas": 0},
"created_at": "2026-09-30T18:54:27+00:00"
}
}
Read
GET /businesses- your businesses, newest first, 50 per page. Followlinks.next.GET /businesses/{external_id}- one business.404 not_foundif it is not yours.
Status
| Field | Values | Meaning |
|---|---|---|
status |
active, suspended |
A PaalChat operator can suspend a business; it then cannot connect or send (409 business_suspended). |
whatsapp.status |
not_connected or a connection state |
connected if any of its WhatsApp accounts is connected, else degraded if any is; otherwise the latest account's state; not_connected if it has none. |