# Tenants

> Your account, its status, retention setting, and how platforms create tenants for their customers.

Canonical: https://docs.whabuzz.com/guides/tenants/

A **tenant** is one business account: its numbers, keys, webhook endpoints and event log. Direct customers have exactly one. Platforms using an [app key](https://docs.whabuzz.com/authentication.md#platform-keys) create one per end customer.

## Your tenant {#your-tenant}

[`GET /v1/tenant`](https://docs.whabuzz.com/api/tenant.md#getTenant) returns your account, its `status`, plan, `retention_days`, and the getting-started checklist (`number_connected`, `api_key_created`, `webhook_verified`, `test_message_sent`). It works in every status, so use it as a health probe for your own credentials.

[`PATCH /v1/tenant`](https://docs.whabuzz.com/api/tenant.md#updateTenant) changes the business name and `retention_days` (see [Retention](https://docs.whabuzz.com/guides/retention.md)).

## Status {#status}

| Status | Meaning |
|---|---|
| `pending_approval` | Signed up, email confirmed, waiting for a WhaBuzz reviewer. |
| `active` | Approved. Everything works. |
| `rejected` | Not approved. The reason is emailed. |
| `suspended` | Paused by WhaBuzz (for example, unpaid invoice past grace, or abuse). Sends stop; inbound is still forwarded. |

What each status allows is in [Authentication](https://docs.whabuzz.com/authentication.md#status).

## Creating tenants for your customers {#platforms}

With an app key:

```bash
curl -X POST https://api.whabuzz.com/v1/tenants \
  -H "Authorization: Bearer $WHABUZZ_APP_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name":"Sunrise Clinic","external_ref":"org_4812"}'
```

See [`POST /v1/tenants`](https://docs.whabuzz.com/api/tenants.md#createTenant), [`GET /v1/tenants`](https://docs.whabuzz.com/api/tenants.md#listTenants) and [`GET /v1/tenants/{tenant_id}`](https://docs.whabuzz.com/api/tenants.md#getTenantById).

Then address that business on every later call with `X-WhaBuzz-Tenant: <tenant_id>`, and connect its number with a hosted [connect session](https://docs.whabuzz.com/guides/numbers.md#hosted-link) so your customer does Meta's popup on a WhaBuzz-hosted page.

Each tenant has its own keys, webhook endpoints, event log and retention. Billing is per tenant: each tenant's connected numbers are billed on that tenant ([Pricing](https://docs.whabuzz.com/pricing.md)).