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

> Create and manage the customer businesses of your partner account.

A tenant is one customer business. Each tenant has its own workspace, its own channels, agents, contacts and
conversations. Nothing is shared between tenants. You name a tenant with your own id, `external_ref`, and use that id in
every later call.

## Create a tenant

```bash theme={null}
curl -X POST https://api.impellabs.tech/api/v1/partner/tenants/ \
  -H "Authorization: Bearer implpk_..." \
  -H "Content-Type: application/json" \
  -d '{
    "external_ref": "acme-001",
    "name": "Acme Dental",
    "owner_email": "owner@yourcompany.test",
    "owner_name": "Sam Rivera",
    "monthly_credit_cap": 5000,
    "plan": "growth"
  }'
```

| Field | Rule |
| - | - |
| `external_ref` | Required. Your id for the business. 120 characters at most. Plain text with no slash. |
| `name` | Required. The business name. |
| `owner_email` | Required. The owner of the workspace. It must not belong to another user. Each tenant needs its own. |
| `monthly_credit_cap` | Required. The most credits the tenant can use in a month. `0` means no cap. |
| `owner_name`, `country`, `phone` | Optional. `country` is two letters. |
| `plan` | Optional. The slug of one of your active plans. Empty means the free plan. An unknown slug answers 400 and names your plans. |

The answer is 201 with the tenant.

```json theme={null}
{
  "external_ref": "acme-001",
  "id": "2f1c0b9e-0000-4000-8000-000000000000",
  "name": "Acme Dental",
  "plan": "growth",
  "status": "active",
  "billed_to": "partner",
  "billing_mode": "payg",
  "monthly_credit_cap": 5000,
  "is_active": true,
  "created_at": "2026-01-15T09:30:00+00:00"
}
```

The owner has no password and gets no email. You set up the tenant with this API. If the person must sign in, set a
password for the owner in the [partner console](https://docs.impellabs.tech/partners/console.md).

A repeat of the call with an `external_ref` that exists answers 200 with that tenant. It switches an offboarded tenant
back on. The body is not checked against a create in that case.

## Credit cap

`monthly_credit_cap` stops the tenant's agents from using more credits than you allow in a month. Change it with
`PATCH`. `0` removes the cap.

## List and read

`GET /api/v1/partner/tenants/` lists your tenants, 100 to a page. Use `q` to find a name or an `external_ref`, and
`status=active` to leave out offboarded tenants. The answer has `results`, `page`, `page_size`, `total` and `has_more`.

`GET /api/v1/partner/tenants/{external_ref}/` reads one tenant.

## Change a tenant

```bash theme={null}
curl -X PATCH https://api.impellabs.tech/api/v1/partner/tenants/acme-001/ \
  -H "Authorization: Bearer implpk_..." \
  -H "Content-Type: application/json" \
  -d '{ "monthly_credit_cap": 8000 }'
```

You can change `name`, `monthly_credit_cap`, `is_active` and `plan`. Send only the fields that change.

## Offboard a tenant

`DELETE /api/v1/partner/tenants/{external_ref}/` offboards the tenant. Its `status` becomes `offboarded`. Nothing is
deleted. Send `PATCH` with `is_active` set to `true` to switch it on again.

## Scope

Every tenant route needs the `tenants:write` scope, also the routes that read.

## Channels, conversations and templates

Use the same `external_ref` for the other routes of a tenant:
[channels](https://docs.impellabs.tech/partners/channels/overview.md), [conversations](https://docs.impellabs.tech/partners/conversations.md) and [templates](https://docs.impellabs.tech/partners/templates.md).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.