Skip to main content

Creating Sub-Accounts

A sub-account is a new Tenant under your billing account. Each one is a fully isolated workspace with its own conversations, contacts, channels, campaigns, and settings. This is the building block for provisioning one workspace per end-customer.

Prerequisites​

  • The user behind your credential must be an owner of the billing account you're adding the tenant to. Only billing-account owners can create additional tenants under an existing billing account.
  • Use a session or token for an account that already has a billing account.

Create a tenant​

POST /api/v1/tenants

Request body​

FieldTypeRequiredDescription
namestringYesDisplay name for the workspace (e.g. your customer's company name).
billing_account_idstringNoThe billing account to attach the tenant to. Provide this to add the sub-account to your existing billing account. If omitted and you already have billing accounts, the request is rejected asking you to specify one.
slugstringNoURL-safe identifier. Auto-generated from name if omitted.
company_emailstringNoContact email for the workspace.
pricing_model_idstringNoPer-tenant pricing override. Inherits from the billing account if not set.
support_emailstringNoSupport email used by default widgets. Defaults to the owner's email.

Other optional fields control workspace defaults (ai_features_enabled, multi_agent_mode, auto_summarize_on_close, auto_transcript_export_format, …) and can be left at their defaults.

curl​

curl -X POST "https://api.sendseven.com/api/v1/tenants" \
  -H "Authorization: Bearer <owner_token_or_session>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Acme Corp",
    "billing_account_id": "ba_your_billing_account",
    "company_email": "[email protected]"
  }'

Response (201 Created)​

{
  "id": "tenant_acme_123",
  "name": "Acme Corp",
  "slug": "acme-corp",
  "billing_account_id": "ba_your_billing_account",
  "pricing_model_id": null,
  "is_trial": true,
  "trial_ends_at": "2026-04-04T00:00:00Z",
  "is_active": true,
  "subscription_tier": "trial",
  "multi_agent_mode": true,
  "auto_summarize_on_close": "ask"
}

Keep the returned id — it's the tenant_id you'll pass as X-Tenant-ID to manage this sub-account from your parent token.

Find your billing account ID

List the billing accounts your user belongs to, then use the one you own as billing_account_id. If you only have one, new tenants attach to it. A brand-new account with no billing account yet will have one created automatically on first tenant creation.

After creating a sub-account​

A freshly created tenant has no channels, contacts, or webhooks. From here you typically:

  1. Register webhooks into it so you receive its events — see Registering webhooks for a sub-account.
  2. Onboard a channel — either connect one via the API, or send the customer a channel connect link.
  3. Drive it from your parent token using X-Tenant-ID — no separate login required.

What you cannot do​

  • You cannot attach a tenant to a billing account you don't own.
  • You cannot move a tenant into a different billing account to cross the isolation boundary — billing accounts are hard isolation boundaries.

Next steps​