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

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

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

The collection is paginated:

{ "results": [...], "page": 1, "page_size": 100, "total": 240, "has_more": true }

Update

PATCH /api/v1/partner/tenants/{external_ref}/
{"monthly_credit_cap": 10000}

Accepts name, monthly_credit_cap, is_active.

Offboard

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

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.

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