# 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:

```text
/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`](/docs/api/upsert-business) 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.

```bash
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"}'
```

```php
$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');
```

```javascript
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();
```

```python
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:

```json
{
  "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`](/docs/api/list-businesses) - your businesses, newest first, 50 per page. Follow `links.next`.
- [`GET /businesses/{external_id}`](/docs/api/get-business) - one business. `404 not_found` if 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](/docs/connect-whatsapp#connection-states) | `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. |

## Next

[Connect the business's WhatsApp](/docs/connect-whatsapp).