Guides

Sub-accounts

Give each customer or team its own isolated workspace and API key, on one shared wallet.

A sub-account is a separate workspace under your account. It has its own agents, numbers, calls, knowledge bases and API key, and it cannot see yours or another sub-account's. It spends your wallet.

Typical uses: one sub-account per client if you resell, or one per business unit.

In the dashboard: Settings → Account → Sub-accounts. Managing sub-accounts needs the admin role or an API key, and your account must be the administrator of its organisation. Accounts created by sign-up are. Otherwise every endpoint here answers 403 Only organization admins can manage sub-accounts.

Create a sub-account

curl -X POST https://api.sevennadi.si/sub-accounts/create \
  -H "Authorization: Bearer vk-0123456789abcdef0123456789abcdef" \
  -H "Content-Type: application/json" \
  -d '{"name": "Example Bank - Collections", "max_concurrency": 5}'

{
  "id": "c1d2e3f4-a5b6-4c7d-8e9f-0a1b2c3d4e5f",
  "name": "Example Bank - Collections",
  "organization_id": "0f9e8d7c-6b5a-4f3e-9d2c-1b0a9f8e7d6c",
  "api_key": "sa-0123456789abcdef0123456789abcdef",
  "multi_tenant": false,
  "min_concurrency": 0,
  "max_concurrency": 5,
  "user_id": "7a6b5c4d-3e2f-4a1b-8c0d-9e8f7a6b5c4d",
  "created_at": "2026-10-13T12:00:00Z",
  "updated_at": "2026-10-13T12:00:00Z"
}

Errors:

The sub-account key

The key starts with sa- followed by 32 hex characters. Use it exactly like any API key:

curl https://api.sevennadi.si/v2/agent/all \
  -H "Authorization: Bearer sa-0123456789abcdef0123456789abcdef"

A request made with it acts inside the sub-account, with admin rights there. It returns only that sub-account's data. Ids from your account, or from a sibling sub-account, answer 404.

Unlike ordinary API keys, a sub-account's key can be read again later: GET /sub-accounts/all returns it for each sub-account. It is stored encrypted. Anyone who can list sub-accounts on the parent can therefore read every sub-account's key.

Concurrency

Three limits apply to a call a sub-account places:

1. The sub-account's own max_concurrency.
2. The organisation's maximum, shared by the parent and all sub-accounts.
3. The sub-account's min_concurrency: while it has fewer live calls than this, it may dial even if the organisation is full.

A call over a limit is not refused. It waits queued until a line frees up. Guaranteed minimums across all sub-accounts must fit within the organisation's own minimum, which the operator sets; with no organisation minimum, leave min_concurrency at 0.

Shared wallet

A sub-account has no money of its own.

• Its calls are charged to the parent's wallet. The ledger entry is on the parent and records which sub-account caused it.
• GET /billing/balance called with a sub-account key shows the parent's balance with "paid_by_parent": true.
• A sub-account sees only the ledger entries it caused.
• It uses the parent's prices and the parent's plan. It cannot top up (A sub-account spends its parent's wallet: add funds on the parent account) or change the plan (A sub-account is on its parent's plan).
• When the parent's wallet is empty, every sub-account's calls stop with balance-low, and their batches wait.

See Billing.

List, update, delete

curl https://api.sevennadi.si/sub-accounts/all \
  -H "Authorization: Bearer vk-0123456789abcdef0123456789abcdef"

Deleting a sub-account revokes its keys at once, so requests with its sa- key start failing. An unknown id is 404 Sub-account not found.

Usage

Usage for one sub-account over a date range (default: the last 30 days):

curl "https://api.sevennadi.si/sub-accounts/c1d2e3f4-a5b6-4c7d-8e9f-0a1b2c3d4e5f/usage?from=2026-10-01&to=2026-10-31" \
  -H "Authorization: Bearer vk-0123456789abcdef0123456789abcdef"

{
  "from": "2026-10-01",
  "to": "2026-10-31T23:59:59.999999+00:00",
  "total_records": 128,
  "total_duration": 5420.5,
  "total_cost": 310.4,
  "total_platform_cost": 180.7,
  "total_telephony_cost": 63.2,
  "status_map": {"completed": 101, "no-answer": 19, "busy": 8},
  "synthesizer_cost_map": {},
  "transcriber_cost_map": {},
  "llm_cost_map": {}
}

• Dates are UTC. A bare to date includes that whole day.
• Durations are seconds. Costs are in minor units of the billing currency, summed from the calls' own cost fields. The numbers above are illustrative.
• The three cost maps break usage down by provider and model.
• A bad date is 400 from/to must be ISO 8601 dates or timestamps.

GET /sub-accounts/all/usage returns the same report for every sub-account in one list, each with its sub_account_id.

In the report, status_map counts calls by final status, so it doubles as a quick health check per client.

Limitations

• A sub-account has no dashboard login of its own. It is used through its API key.
• There is no separate wallet, spending cap or credit limit per sub-account. One sub-account can spend the whole parent balance.
• Sub-accounts cannot be nested.
• The key cannot be rotated in place. To replace it, delete the sub-account and create a new one, which also means new agents and numbers.
• Extra tenant database fields accepted on create (db_host, db_name, db_port, db_user, db_password) are stored but not used: all sub-accounts share the platform's database.

For field-level detail see Sub-accounts reference.