> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.agentphone.to/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.agentphone.to/_mcp/server.

# Sub-Accounts

> Create isolated sub-accounts for separate campaigns, brands, or clients under one master account.

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

```typescript
import AgentPhone from 'agentphone';
const client = new AgentPhone({ apiKey: 'sk_live_...' });

const sub = await client.subAccounts.create({ name: 'Marketing' });
console.log(sub.id); // use this ID to target the sub-account
```

```python
from agentphone import AgentPhone
client = AgentPhone(api_key="sk_live_...")

sub = client.sub_accounts.create(name="Marketing")
print(sub.id)  # use this ID to target the sub-account
```

```bash
curl -X POST https://api.agentphone.ai/v1/sub-accounts \
  -H "Authorization: Bearer sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{"name": "Marketing"}'
```

## 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.

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

```python
# List numbers in the "Marketing" sub-account
numbers = client.numbers.list(
    headers={"X-Sub-Account-Id": sub.id}
)
```

```bash
# List numbers in the "Marketing" sub-account
curl https://api.agentphone.ai/v1/numbers \
  -H "Authorization: Bearer sk_live_..." \
  -H "X-Sub-Account-Id: cmps2uxc5000536awd6zu8rtr"
```

### Example: full workflow

```bash
# 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

| Feature                  | Shared with parent | Isolated per sub-account |
| ------------------------ | ------------------ | ------------------------ |
| Billing wallet (credits) | Yes                | -                        |
| API keys                 | Yes                | -                        |
| Team members             | Yes                | -                        |
| Agents                   | -                  | Yes                      |
| Phone numbers            | -                  | Yes                      |
| Conversations & messages | -                  | Yes                      |
| Voice calls              | -                  | Yes                      |
| Webhooks                 | -                  | Yes                      |
| 10DLC registration       | -                  | Yes                      |
| Contacts                 | -                  | Yes                      |

## Limits

* Maximum **500 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