# Tenants

> Platform (app) keys only. Create and list the businesses you manage.

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

Platform (app) keys only. Create and list the businesses you manage.

Base URL `https://api.whabuzz.com`. Every request needs `Authorization: Bearer <key>` unless the operation says otherwise; see [Authentication](https://docs.whabuzz.com/authentication.md). Errors follow the [two-source contract](https://docs.whabuzz.com/errors.md).

Operations on this page:

- [`GET /v1/tenants`](#listTenants): List tenants created by your app key
- [`POST /v1/tenants`](#createTenant): Create a tenant for one of your customers
- [`GET /v1/tenants/{tenant_id}`](#getTenantById): Get one of your app's tenants

## List tenants created by your app key {#listTenants}

`GET /v1/tenants`

**Auth:** API key (tenant key, or app key with `X-WhaBuzz-Tenant`). **Operation id:** `listTenants`.

**Parameters**

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `limit` | query | integer | no |  |
| `cursor` | query | string | no | `next_cursor` from the previous page. |
| `external_ref` | query | string | no |  |

cURL:

```bash
curl -X GET "https://api.whabuzz.com/v1/tenants" \
  -H "Authorization: Bearer $WHABUZZ_KEY"
```

**Responses**

**200** Tenants

```json
{
  "data": [
    {
      "id": "7d0f3c1e-2b8a-4c55-9f61-0e9b1a2c3d4e",
      "name": "Sunrise Clinic",
      "external_ref": "org_4812",
      "status": "active",
      "created_at": "2026-10-16T10:00:00Z"
    }
  ],
  "next_cursor": null
}
```

**Common errors.** Shape and meanings are on the [Errors page](https://docs.whabuzz.com/errors.md).

| HTTP | WhaBuzz code | Meaning |
|---|---|---|
| 403 | `forbidden` | Not allowed for this caller |

## Create a tenant for one of your customers {#createTenant}

`POST /v1/tenants`

Tenants created with an app key are active immediately. Connect their number with a Connect session.

**Auth:** API key (tenant key, or app key with `X-WhaBuzz-Tenant`). **Operation id:** `createTenant`.

**Request body** (`application/json`, required)

| Field | Type | Required | Description |
|---|---|---|---|
| `name` | string | yes |  |
| `external_ref` | string | no | Your own id for this business. Unique per app. |
| `retention_days` | `30` or `90` or `180` or `365` | no | Default `90`. |

Request example:

```json
{
  "name": "Sunrise Clinic",
  "external_ref": "org_4812"
}
```

cURL:

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

**Responses**

**201** Created

```json
{
  "id": "7d0f3c1e-2b8a-4c55-9f61-0e9b1a2c3d4e",
  "name": "Sunrise Clinic",
  "external_ref": "org_4812",
  "status": "active",
  "retention_days": 90,
  "created_at": "2026-10-16T10:00:00Z"
}
```

**Common errors.** Shape and meanings are on the [Errors page](https://docs.whabuzz.com/errors.md).

| HTTP | WhaBuzz code | Meaning |
|---|---|---|
| 400 | `invalid_request` | Invalid request |
| 403 | `forbidden` | Not allowed for this caller |

## Get one of your app's tenants {#getTenantById}

`GET /v1/tenants/{tenant_id}`

**Auth:** API key (tenant key, or app key with `X-WhaBuzz-Tenant`). **Operation id:** `getTenantById`.

**Parameters**

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `tenant_id` | path | string (uuid) | yes |  |

cURL:

```bash
curl -X GET "https://api.whabuzz.com/v1/tenants/$TENANT_ID" \
  -H "Authorization: Bearer $WHABUZZ_KEY"
```

**Responses**

**200** Tenant

```json
{
  "id": "7d0f3c1e-2b8a-4c55-9f61-0e9b1a2c3d4e",
  "name": "Sunrise Clinic",
  "external_ref": "org_4812",
  "status": "active"
}
```

**Common errors.** Shape and meanings are on the [Errors page](https://docs.whabuzz.com/errors.md).

| HTTP | WhaBuzz code | Meaning |
|---|---|---|
| 404 | `not_found` | Not found |