Trillet AI logo

Tenants

Create, update, suspend, delete and restore a workspace for each of your customers with Trillet OEM.

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.

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

{
  "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"
}
FieldNotes
idThe tenant ID. Use it in paths and as x-workspace-id on standard endpoints.
externalIdYour ID for this customer, 1 to 128 characters with no leading or trailing spaces. Unique among your live tenants. Look tenants up by it.
statusactive, suspended, deleted or provisioning_failed
regionus or au. Set at creation; decides where call data is stored.
metadataUp to 8 KB of your own JSON data. Trillet does not read it.
limits.monthlySpendCapOptional monthly spend cap in USD, or null. See Usage and spend caps.

Endpoints

MethodPathScope
POST/partner/v1/tenantstenants:write
GET/partner/v1/tenantstenants: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}/suspendtenants:write
POST/partner/v1/tenants/{tenantId}/resumetenants:write
DELETE/partner/v1/tenants/{tenantId}tenants:write
POST/partner/v1/tenants/{tenantId}/restoretenants:write

Create a tenant

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 }
  }'
externalIdstringrequired

Your ID for this customer.

namestringrequired

Display name, up to 100 characters.

regionstring

us or au. Defaults to your partner account's region.

metadataobject

Your own data, up to 8 KB.

limits.monthlySpendCapnumber | null

Monthly spend cap in USD, 0 or more. null or leaving it out creates the tenant with no cap. See Spend caps.

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).

Each tenant has a wallet linked to your account and starts with no agents, flows or numbers. Build them with the standard endpoints and the tenant ID in x-workspace-id.

StatusCodeWhen
409tenant_existsA live tenant already has this externalId
409tenant_deleted_restorableA deleted tenant with this externalId can still be restored
409tenant_limit_reachedYour account is at its tenant limit (maxTenants on GET /key)
400invalid_request, invalid_external_id, invalid_name, invalid_metadata, invalid_limitsA field is invalid. error.param names it when the request failed schema validation.
400invalid_regionThe region you asked for, or your account's default region, is not available. Contact your account manager.

List and look up tenants

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.

Update a tenant

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 } }'
namestring

New display name.

metadataobject

Replaces the whole metadata object.

limits.monthlySpendCapnumber | null

Monthly spend cap in USD, 0 or more. null removes the cap.

Suspend and resume

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

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.

Adopting an existing client workspace as a tenant, and installing a template at creation, are planned.

Last updated on