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

import { AgentPhoneClient } from "agentphone";
const client = new AgentPhoneClient({ token: process.env.AGENTPHONE_API_KEY!, maxRetries: 0 });
const sub = await client.subAccounts.createSubAccount({ name: "Marketing" });
if (!sub || typeof sub !== "object" || !("id" in sub) || typeof sub.id !== "string") {
  throw new Error("Expected a sub-account ID");
}
const subId = sub.id;
console.log(subId);

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. Scope agents, numbers, messages, calls, and webhooks consistently. Most requests without the header target the master account; registration status can resolve a child campaign, so pass the header explicitly when diagnosing it. Billing and API-key management remain on the master account.

// List numbers in the "Marketing" sub-account
const numbers = await client.numbers.listNumbers({}, {
  headers: { "X-Sub-Account-Id": subId },
  queryParams: { limit: 20 },
});

Example: full workflow

Create the sub-account, then create its agent and number with the same header. The number purchase below incurs its provisioning charge. Requires curl and jq.

set -euo pipefail
: "${AGENTPHONE_API_KEY:?Set AGENTPHONE_API_KEY}"
API=https://api.agentphone.ai
SUB_ID=$(curl --fail-with-body -sS "$API/v1/sub-accounts" \
  -H "Authorization: Bearer $AGENTPHONE_API_KEY" -H 'Content-Type: application/json' \
  -d '{"name":"Marketing"}' | jq -er '.id')
AGENT_ID=$(curl --fail-with-body -sS "$API/v1/agents" \
  -H "Authorization: Bearer $AGENTPHONE_API_KEY" -H "X-Sub-Account-Id: $SUB_ID" \
  -H 'Content-Type: application/json' \
  -d '{"name":"Marketing Bot","voiceMode":"hosted","systemPrompt":"Help callers with product questions."}' | jq -er '.id')
curl --fail-with-body -sS "$API/v1/numbers" \
  -H "Authorization: Bearer $AGENTPHONE_API_KEY" -H "X-Sub-Account-Id: $SUB_ID" \
  -H 'Content-Type: application/json' \
  -d "$(jq -n --arg agent "$AGENT_ID" '{country:"US",agentId:$agent}')"

Complete SMS registration in this same account scope before outbound SMS. A registration submitted from the parent creates another sub-account by default; do not accidentally register a different campaign environment.

What’s shared vs. isolated

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