---
title: "Tenants"
sidebarTitle: "Tenants"
description: "Create, update, suspend, delete and restore a workspace for each of your customers with Trillet OEM."
lastUpdated: "2026-11-04"
---

> **For AI agents:** the complete documentation index is at [llms.txt](https://trillet-ai.jamdesk.app/llms.txt). Append `.md` to any page URL for its markdown version.

<Note>
  **Early access.** Trillet OEM is built and in testing with design partners. Contact your account manager to have it enabled for your account. Details may still change.
</Note>

A tenant is one of your customers. It is an isolated workspace with its own agents, phone numbers, call history, knowledge bases, workflows and usage. Tenants inherit your white-label branding when your account has white-label enabled, and they draw on your account for billing, so a tenant never needs its own card or balance.

## The tenant object

```json
{
  "object": "tenant",
  "id": "d9d9d9d9d9d9d9d9d9d9d9d9",
  "externalId": "cust_8842",
  "name": "Harbour Dental",
  "status": "active",
  "region": "us",
  "metadata": { "plan": "pro", "crmAccountId": "0015g00000X" },
  "limits": { "monthlySpendCap": 500 },
  "suspendedAt": null,
  "suspendedReason": null,
  "deletedAt": null,
  "createdAt": "2026-11-02T10:14:00.000Z"
}
```

| Field | Notes |
|---|---|
| `id` | The tenant ID. Use it in paths and as `x-workspace-id` on standard endpoints. |
| `externalId` | Your ID for this customer, 1 to 128 characters with no leading or trailing spaces. Unique among your live tenants. Look tenants up by it. |
| `status` | `active`, `suspended`, `deleted` or `provisioning_failed` |
| `region` | `us` or `au`. Set at creation; decides where call data is stored. |
| `metadata` | Up to 8 KB of your own JSON data. Trillet does not read it. |
| `limits.monthlySpendCap` | Optional monthly spend cap in USD, or `null`. See [Usage and spend caps](https://trillet-ai.jamdesk.app/voice-engine/usage-and-billing#spend-caps). |

## Endpoints

| Method | Path | Scope |
|---|---|---|
| `POST` | `/partner/v1/tenants` | `tenants:write` |
| `GET` | `/partner/v1/tenants` | `tenants:read` |
| `GET` | `/partner/v1/tenants/{tenantId}` | `tenants:read` |
| `GET` | `/partner/v1/tenants/by-external-id/{externalId}` | `tenants:read` |
| `PATCH` | `/partner/v1/tenants/{tenantId}` | `tenants:write` |
| `POST` | `/partner/v1/tenants/{tenantId}/suspend` | `tenants:write` |
| `POST` | `/partner/v1/tenants/{tenantId}/resume` | `tenants:write` |
| `DELETE` | `/partner/v1/tenants/{tenantId}` | `tenants:write` |
| `POST` | `/partner/v1/tenants/{tenantId}/restore` | `tenants:write` |

## Create a tenant

```bash
curl -X POST https://api.trillet.ai/partner/v1/tenants \
  -H "Authorization: Bearer tpk_live_..." \
  -H "Idempotency-Key: create-tenant-cust_8842" \
  -H "Content-Type: application/json" \
  -d '{
    "externalId": "cust_8842",
    "name": "Harbour Dental",
    "region": "us",
    "metadata": { "plan": "pro" },
    "limits": { "monthlySpendCap": 500 }
  }'
```

<ParamField body="externalId" type="string" required>
  Your ID for this customer.
</ParamField>
<ParamField body="name" type="string" required>
  Display name, up to 100 characters.
</ParamField>
<ParamField body="region" type="string">
  `us` or `au`. Defaults to your partner account's region.
</ParamField>
<ParamField body="metadata" type="object">
  Your own data, up to 8 KB.
</ParamField>
<ParamField body="limits.monthlySpendCap" type="number | null">
  Monthly spend cap in USD, 0 or more. `null` or leaving it out creates the tenant with no cap. See [Spend caps](https://trillet-ai.jamdesk.app/voice-engine/usage-and-billing#spend-caps).
</ParamField>

Returns `201` with the tenant. `Idempotency-Key` is required.

If the workspace is created but its setup does not complete, the tenant is returned with status `provisioning_failed`. Contact support with the tenant ID. If you delete it instead, its `externalId` stays reserved for 30 days (see [Delete and restore](#delete-and-restore)).

Each tenant has a wallet linked to your account and starts with no agents, flows or numbers. Build them with the [standard endpoints](https://trillet-ai.jamdesk.app/voice-engine/authentication#calling-standard-endpoints-for-a-tenant) and the tenant ID in `x-workspace-id`.

| Status | Code | When |
|---|---|---|
| `409` | `tenant_exists` | A live tenant already has this `externalId` |
| `409` | `tenant_deleted_restorable` | A deleted tenant with this `externalId` can still be restored |
| `409` | `tenant_limit_reached` | Your account is at its tenant limit (`maxTenants` on [`GET /key`](https://trillet-ai.jamdesk.app/voice-engine/authentication#check-a-key)) |
| `400` | `invalid_request`, `invalid_external_id`, `invalid_name`, `invalid_metadata`, `invalid_limits` | A field is invalid. `error.param` names it when the request failed schema validation. |
| `400` | `invalid_region` | The region you asked for, or your account's default region, is not available. Contact your account manager. |

## List and look up tenants

```bash
curl "https://api.trillet.ai/partner/v1/tenants?status=active&limit=50" \
  -H "Authorization: Bearer tpk_live_..."

curl https://api.trillet.ai/partner/v1/tenants/by-external-id/cust_8842 \
  -H "Authorization: Bearer tpk_live_..."
```

`GET /tenants` accepts `status` (`active`, `suspended` or `provisioning_failed`), `externalId`, `limit` and `starting_after`. Deleted tenants are not listed or returned by `GET`; keep the ID if you may restore it. A `starting_after` that is not a tenant ID returns `400` `invalid_cursor`. See [Pagination](https://trillet-ai.jamdesk.app/voice-engine/conventions#pagination).

## Update a tenant

```bash
curl -X PATCH https://api.trillet.ai/partner/v1/tenants/d9d9d9d9d9d9d9d9d9d9d9d9 \
  -H "Authorization: Bearer tpk_live_..." \
  -H "Content-Type: application/json" \
  -d '{ "name": "Harbour Dental Group", "limits": { "monthlySpendCap": 750 } }'
```

<ParamField body="name" type="string">
  New display name.
</ParamField>
<ParamField body="metadata" type="object">
  Replaces the whole metadata object.
</ParamField>
<ParamField body="limits.monthlySpendCap" type="number | null">
  Monthly spend cap in USD, 0 or more. `null` removes the cap.
</ParamField>

## Suspend and resume

Suspending a tenant stops its traffic but keeps everything else. Use it for unpaid accounts, offboarding or abuse.

```bash
curl -X POST https://api.trillet.ai/partner/v1/tenants/d9d9d9d9d9d9d9d9d9d9d9d9/suspend \
  -H "Authorization: Bearer tpk_live_..." \
  -H "Content-Type: application/json" \
  -d '{ "reason": "Invoice overdue" }'
```

While a tenant is suspended:

- Outbound calls, web calls and SMS are refused with `403` and code `workspace_suspended`.
- New workflow runs are recorded as skipped, with skip reason `workspace_suspended`.
- Inbound calls are answered and ended straight away, with no speech, and recorded in call history with status `blocked`.
- You cannot buy numbers for it (`409` `tenant_suspended`).
- Numbers, agents, configuration and history are kept. You can still read and change them.

`POST /resume` restores traffic immediately. `reason` is optional, up to 500 characters (`400` `invalid_request` otherwise), and is returned as `suspendedReason`.

## Delete and restore

`DELETE` releases the tenant's numbers (each one sends `number.released` with `reason: "tenant_deleted"`), soft-deletes its flows, agents and knowledge bases, and soft-deletes the tenant. It returns the tenant with status `deleted`.

`POST /restore` brings a deleted tenant back within 30 days. After that it returns `410` `restore_window_expired`. Other restore errors: `409` `tenant_not_deleted`, and `409` `tenant_exists` if a live tenant has taken its `externalId` since.

While a deleted tenant can still be restored, creating a new tenant with the same `externalId` returns `409` `tenant_deleted_restorable`. After 30 days the `externalId` is free again.

A delete already in progress returns `409` `tenant_delete_in_progress`.

## Events

Tenant changes emit `tenant.created`, `tenant.updated`, `tenant.suspended`, `tenant.resumed`, `tenant.deleted` and `tenant.restored`. See [Events](https://trillet-ai.jamdesk.app/voice-engine/events).

<Note>
  Adopting an existing client workspace as a tenant, and installing a [template](https://trillet-ai.jamdesk.app/voice-engine/templates) at creation, are planned.
</Note>
