Tenants

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

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.

{
  "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. 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

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, conversations and templates.

Get started

Customers

Channels

Events

Partner API reference