Sub-Accounts

Sub-accounts let you run multiple isolated environments under a single master account. Each sub-account gets its own agents, phone numbers, conversations, calls, webhooks, and 10DLC registration, while sharing the master account’s billing wallet and API key.

When to use sub-accounts

• Multiple 10DLC campaigns (e.g. Marketing vs. Customer Care)
• Multi-brand support (separate phone presence per brand)
• Client isolation (agencies managing multiple clients)
• Dev/staging environments alongside production

How it works

A sub-account is a fully isolated account linked to a parent. Every feature (agents, numbers, messages, calls, webhooks) is scoped to the sub-account. Billing draws from the parent’s wallet.

Master Account (billing, API keys)
├── Sub-Account "Marketing"  (own agents, numbers, messages, calls)
├── Sub-Account "Support"    (own agents, numbers, messages, calls)
└── Sub-Account "Client X"   (own agents, numbers, messages, calls)

Create a sub-account

1
import AgentPhone from 'agentphone';
2
const client = new AgentPhone({ apiKey: 'sk_live_...' });
3
4
const sub = await client.subAccounts.create({ name: 'Marketing' });
5
console.log(sub.id); // use this ID to target the sub-account

Target a sub-account with X-Sub-Account-Id

Use your master API key with the X-Sub-Account-Id header to operate on any sub-account. Every endpoint works the same way. No header means the request targets the master account.

1
// List numbers in the "Marketing" sub-account
2
const numbers = await client.numbers.list({
3
  headers: { 'X-Sub-Account-Id': sub.id }
4
});

Example: full workflow

$
# 1. Create a sub-account
$
SUB_ID=$(curl -s -X POST https://api.agentphone.ai/v1/sub-accounts \
>
  -H "Authorization: Bearer sk_live_..." \
>
  -H "Content-Type: application/json" \
>
  -d '{"name": "Marketing"}' | jq -r .id)
$
$
# 2. Buy a number in it
$
curl -X POST https://api.agentphone.ai/v1/numbers \
>
  -H "Authorization: Bearer sk_live_..." \
>
  -H "X-Sub-Account-Id: $SUB_ID" \
>
  -H "Content-Type: application/json" \
>
  -d '{"country": "US"}'
$
$
# 3. Create an agent in it
$
curl -X POST https://api.agentphone.ai/v1/agents \
>
  -H "Authorization: Bearer sk_live_..." \
>
  -H "X-Sub-Account-Id: $SUB_ID" \
>
  -H "Content-Type: application/json" \
>
  -d '{"name": "Marketing Bot", "voiceMode": "hosted", "systemPrompt": "You help with marketing inquiries."}'
$
$
# 4. List all sub-accounts
$
curl https://api.agentphone.ai/v1/sub-accounts \
>
  -H "Authorization: Bearer sk_live_..."

What’s shared vs. isolated

Limits

• Maximum 25 sub-accounts per master account
• Sub-accounts cannot create their own sub-accounts (one level only)
• Sub-accounts cannot create API keys or modify billing settings

Dashboard access

Sub-accounts are also accessible from the AgentPhone dashboard:

1. Go to Settings on the master account
2. Find the Sub-Accounts section
3. Click Create to add a new sub-account
4. Click any sub-account to switch into it and see its full dashboard
5. Use the “Back to main account” banner to return