> ## Documentation Index
> Fetch the complete documentation index at: https://docs.impellabs.tech/llms.txt
> Use this file to discover all available pages before exploring further.

# Tenants

> Provisioning, listing and offboarding the businesses you serve.

A tenant is one of your merchants. You address it by `external_ref` — **your**
id for that business — in every path.

## Provision

```http theme={null}
POST /api/v1/partner/tenants/
```

| Field                | Required | Notes                                         |
| -------------------- | -------- | --------------------------------------------- |
| `external_ref`       | yes      | Your id. URL-safe: no slashes, and not `list` |
| `name`               | yes      | The business name                             |
| `owner_email`        | yes      | Contact address. No mail is sent to it        |
| `monthly_credit_cap` | yes      | Credits per month before the assistant pauses |
| `owner_name`         | no       |                                               |
| `country`            | no       | ISO-3166 alpha-2                              |
| `phone`              | no       | E.164                                         |

### Idempotency

Keyed on `(you, external_ref)`. A repeat returns **200** with the existing
tenant instead of **201** with a duplicate, so a retry after a timeout is safe.
The uniqueness is enforced by the database, not just checked, so two concurrent
requests cannot both win.

Re-provisioning an offboarded tenant **revives** it rather than returning a
dead record.

## Read and list

```http theme={null}
GET /api/v1/partner/tenants/                    # ?q= &status=active &page=
GET /api/v1/partner/tenants/{external_ref}/
```

The collection is paginated:

```json theme={null}
{ "results": [...], "page": 1, "page_size": 100, "total": 240, "has_more": true }
```

## Update

```http theme={null}
PATCH /api/v1/partner/tenants/{external_ref}/
{"monthly_credit_cap": 10000}
```

Accepts `name`, `monthly_credit_cap`, `is_active`.

## Offboard

```http theme={null}
DELETE /api/v1/partner/tenants/{external_ref}/
```

A soft offboard. The assistant stops, the data stays, and the tenant remains
readable — you can still see its state, and re-provisioning brings it back.
Nothing is destroyed by an API call.

## Isolation

<Note>
  A tenant belonging to another partner returns **404**, never 403. That is
  deliberate: a 403 would confirm the id exists, which would let anyone walk a
  competitor's customer list one guess at a time. An id you do not own and an id
  that does not exist are indistinguishable to you.
</Note>

The same rule applies to every path under `tenants/{external_ref}/` — knowledge,
assistants, tools, channels.