Managing subaccounts

Subaccounts let one main account manage several separate workspaces, for example one per client if you’re an agency, or one per brand or region. Each subaccount has its own agents, contacts, phone numbers, members, and results. You control each subaccount’s limits and permissions from the main account.

How subaccounts work

One level deep. A main account can have many subaccounts. Subaccounts can’t have their own subaccounts.
Main account members have access to every subaccount. Admins of the main account can open any subaccount and change its settings.
Subaccount members see only their subaccount. Invite your client’s team directly into their subaccount.
The main account sets the boundaries. Dial-attempt limits, usage limits, feature permissions, and available apps are set per subaccount by the main account.
Branding is shared. If your main account uses white label, its subaccounts use the same logo and custom domain.

Create a subaccount

Open Subaccounts

In your main account, click your name in the sidebar, choose Settings, and open Subaccounts. Only Admins of a main account see this section.

Start a new subaccount

Click Create. If you don’t have subaccounts yet, the page shows Are you an Agency?. Click Create Subaccount.

Name it

Enter a Subaccount Name, for example your client’s company name, and click Create.

New Subaccount dialog with a Subaccount Name field containing Demo Client and Cancel and Create buttons — The New Subaccount dialog.

The new subaccount appears in the table with its Name, Date of creation, number of Members, and number of Agents.

If Create Subaccount is disabled or the Subaccounts section is missing, subaccounts aren’t available on your account. Email .

Switch between accounts

Use either of these:

Account switcher. Click your organization name at the top of the sidebar and pick the subaccount. Choose Manage Subaccounts from the same menu to jump to the subaccounts list.
Settings. In Settings → Subaccounts, click a subaccount, then use the enter option on the account card at the top to open it. Click Back to return to the list.

The sidebar always shows which account you’re working in. Agents, contacts, and phone numbers you create go into that account.

Configure a subaccount

In Settings → Subaccounts, click a subaccount to open its settings. The panel includes these sections:

Section	What you can do
General	Rename the subaccount, and set its retention period, support access, and MFA. See Security and privacy.
Limits	Cap dial attempts, usage, and concurrency. See Limits.
Permissions	Turn features and apps on or off for the subaccount’s members. See Permissions.
Members	Invite members, change roles and access, or remove members.
Agents	See the subaccount’s agents. Shown only when it has agents.
Webhooks	Send events from all of the subaccount’s agents to your endpoints. See Webhooks.

To delete a subaccount, click Delete Subaccount at the bottom of its settings and confirm.

You can’t undo deleting a subaccount. Export any contacts and call data you need before you delete it.

Limits

Setting	What it does
Max Total Dial Attempts	The highest number of dial attempts per contact that the subaccount’s agents can use. It can’t be higher than the main account’s maximum.
Outgoing Agent	Caps the subaccount’s total outbound usage, in Contacts or Minutes. Choose whether to Stop dialing new contacts when the cap is reached (on by default) and whether to Send notification. When you turn it on, the cap starts at 1,000 contacts.
Limit Outgoing Concurrent Calls	Sets Max Outgoing Calls in Parallel for the subaccount. Turn it off to let calls run as fast as possible.
Incoming Agent	Caps total inbound usage, in Calls or Minutes. When you turn it on, the cap starts at 5,000 calls.

Permissions

Permissions apply only to members of the subaccount. Members of the main account keep full access. Only permissions that the main account has can be turned on for a subaccount.

Permission	When turned off, subaccount members can’t…
Manage Members	Manage the subaccount’s members.
VOIP and phone numbers	View or set up the phone system.
Select phone numbers in Agents	Choose phone numbers in an agent’s settings.
Scan phone numbers for SPAM	Run spam checks on phone numbers.
API Keys	Create or use API keys.
Analytics	Open the Analytics page.
Limit concurrent calls	Change call concurrency limits.
Studio Chat	Use Studio Chat, the AI assistant.

Sensitive content restriction works the other way around: when turned on, it hides transcripts and recordings of conversations that contain sensitive data. See Security and privacy. Click App Management to choose which App Center apps the subaccount can use. In the subaccount’s own settings, members see an info icon on features that are available because the main account turned them on.

Members

Each subaccount has its own team. Open the subaccount’s Members section, or switch into the subaccount and use Settings → Team. Inviting, roles, and access toggles work as described in Team and permissions. If you invite someone who is already a member of the main account, Callers tells you they already have a role there. They can already reach the subaccount.

Manage subaccounts with the API

Use an API key from the main account. The Subaccounts and SIP API guide covers the full endpoint set. Create a subaccount with POST /organization/sub-organization. name and retryAttemptsMaxValue (1–10) are required. You can also set limits, permissions, and webhooks.

curl -X POST https://api.callers.ai/organization/sub-organization \
  -H "Authorization: $CALLERS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Acme Dental",
    "retryAttemptsMaxValue": 5,
    "limits": { "outgoingContacts": 2000, "incomingCalls": null },
    "permissions": ["permission_enable_analytics", "permission_enable_manage_members"],
    "webhooks": [{ "url": "https://example.com/callers-events" }]
  }'

const res = await fetch("https://api.callers.ai/organization/sub-organization", {
  method: "POST",
  headers: {
    Authorization: process.env.CALLERS_API_KEY,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    name: "Acme Dental",
    retryAttemptsMaxValue: 5,
    permissions: ["permission_enable_analytics"],
  }),
});
const { id } = await res.json(); // ID of the new subaccount

import os
import requests

res = requests.post(
    "https://api.callers.ai/organization/sub-organization",
    headers={"Authorization": os.environ["CALLERS_API_KEY"]},
    json={
        "name": "Acme Dental",
        "retryAttemptsMaxValue": 5,
        "permissions": ["permission_enable_analytics"],
    },
)
subaccount_id = res.json()["id"]

When you add webhooks without events, they receive the default post-call outcome events. See the API reference for the full list of permissions and events. Act inside a subaccount by adding the x-sub-organization-id header to any request:

curl https://api.callers.ai/agents \
  -H "Authorization: $CALLERS_API_KEY" \
  -H "x-sub-organization-id: <subaccount-id>"

The subaccount must belong to the main account that owns the key. Otherwise the request is rejected. Delete a subaccount with DELETE /organization/{id}.

Troubleshooting

I don't see Subaccounts in Settings

The section appears only for Admins of a main account. It isn’t shown inside a subaccount. If you’re an Admin of the main account and still don’t see it, contact support.

A subaccount member can't find a feature

The main account may have turned off that permission or app for the subaccount. Check the subaccount’s Permissions and App Management.

I can't raise Max Total Dial Attempts

A subaccount can’t go above the main account’s maximum.

White label

Your logo, domain, and app credentials.

Team and permissions

Roles and member access.

API keys

Authenticate API requests.

Scheduling and retries

Dial attempts and concurrency for agents.

Get started

Build your agent

Test and deploy

Voice

Channels

Contacts and outreach

Results and analytics

Human operators

Best practices

Account and administration

Enterprise

Resources

Managing subaccounts

How subaccounts work

Create a subaccount

Switch between accounts

Configure a subaccount

Limits

Permissions

Members

Manage subaccounts with the API

Troubleshooting

White label

Team and permissions

API keys

Scheduling and retries

​How subaccounts work

​Create a subaccount

​Switch between accounts

​Configure a subaccount

​Limits

​Permissions

​Members

​Manage subaccounts with the API

​Troubleshooting

​Related

White label

Team and permissions

API keys

Scheduling and retries

How subaccounts work

Create a subaccount

Switch between accounts

Configure a subaccount

Limits

Permissions

Members

Manage subaccounts with the API

Troubleshooting

Related