> ## Documentation Index
> Fetch the complete documentation index at: https://www.vobiz.ai/docs/llms.txt
> Use this file to discover all available pages before exploring further.
# Vobiz sub-accounts vs partner accounts
> Choose between Vobiz sub-accounts and partner child accounts for a multi-customer platform - how balance, KYC, phone numbers, CPS, and concurrency behave in each model.
If you run a platform that serves many customers on Vobiz, such as an AI voice agent product, a CRM with calling, or a reseller business, you need a separate Vobiz identity for each customer. Vobiz gives you two ways to do that: **sub-accounts** and **partner child accounts**.
Both let you provision customers programmatically. They differ in who owns five things: **balance**, **KYC**, **phone numbers**, **CPS** (calls per second), and **concurrency** (simultaneous calls). This page explains each model and helps you pick one. Many platforms use both.
Isolated customers inside your main account. One wallet, one capacity pool, your pricing. You stay in the loop.
Each customer becomes a full Vobiz account you created. Own wallet, own capacity, own KYC. Vobiz works with them directly.
## The two models at a glance
In the **sub-account** model, your main account (`MA_…`) holds the balance, the CPS limit, and the concurrency limit. Every sub-account (`SA_…`) lives inside it. Each sub-account carries its own phone numbers and, for real customers, its own KYC.
In the **partner** model, your partner master account creates child accounts. Each child account is a main account in its own right (`MA_…`) with its own balance, CPS, concurrency, KYC, and numbers. You can top those up from your master account, but the child account owns them.
## Side-by-side comparison
| | Sub-account | Partner child account |
| - | - | - |
| **Balance** | Shared. All usage is charged to your main account's wallet. | Separate. Each child account has its own wallet. You fund it with a [balance transfer](/docs/partner/api/balance), or Vobiz invoices the customer directly. |
| **KYC** | `personal_use` inherits your KYC. `customer_use` needs its own KYC before it can place calls. | Each child account completes its own KYC through a [partner KYC session](/docs/partner/api/kyc-sessions). |
| **Phone numbers** | Buy with the main account and assign to a sub-account, or let the sub-account buy its own. Either way the number is used under the sub-account's KYC. | Bought and assigned to the child account under its KYC. |
| **CPS** | One limit on the main account, pooled across every sub-account. | Own limit per child account. You [transfer or reclaim CPS](/docs/partner/api/capacity) from your partner pool. |
| **Concurrency** | One limit on the main account, pooled across every sub-account. | Own limit per child account. You [transfer or reclaim concurrency](/docs/partner/api/capacity) from your partner pool. |
| **Pricing shown to the customer** | Yours. The customer never sees Vobiz rates, so you set your own markup. | The customer has a full Vobiz account and sees their own usage and balance. |
| **Who Vobiz contacts** | You. Account notices and compliance matters come to the main account. | The customer. Vobiz works with the child account directly. |
| **API access** | Your main-account credentials provision everything. Each sub-account also gets its own `auth_id` and `auth_token`. | You hold the child account's `auth_id` and `auth_token`, so you can act on its behalf through the full Vobiz API. |
| **Best for** | Platforms that want one bill, one capacity pool, and their own pricing. | Platforms whose customers should be billed, supported, and capacity-managed as independent Vobiz customers. |
## How each resource behaves
### Balance
With **sub-accounts**, there is one wallet. Every call from every sub-account draws from your main account's balance. Vobiz charges you, never your customer, so you decide what to show and charge your customer. That makes sub-accounts the natural fit for a markup model: Vobiz charges you one rate and you bill your customer another.
With **partner accounts**, each child account has its own wallet. You can fund it from your master balance, and the transfer is atomic and recorded in both ledgers. If you would rather not carry a large customer's spend on your own books, Vobiz can also invoice that customer directly. Partners often choose this for their largest accounts so they do not have to clear big invoices on the customer's behalf.
```mermaid theme={null}
sequenceDiagram
participant Cust as Your customer
participant You as Your platform
participant Vobiz
Note over Cust,Vobiz: Sub-account model
Cust->>You: Pays your price
You->>Vobiz: Main account wallet pays the Vobiz rate
Vobiz-->>You: Usage charged to the MA_… balance
Note over Cust,Vobiz: Partner model
You->>Vobiz: Transfer balance to the child account (optional)
Vobiz->>Cust: Or Vobiz invoices the customer directly
Vobiz-->>Cust: Usage charged to the child account's own wallet
```
### KYC
In India, the number used to call a person must be linked to the KYC of the business that actually makes those calls. If every customer's number sits on your own KYC, that becomes a problem as you grow. Both models solve it.
* **Sub-accounts** support two modes. `personal_use` inherits your main account's KYC and suits internal teams, staging, and your own workloads. `customer_use` requires the sub-account to complete its own KYC and starts with `kyc_calls_blocked: true` until it does. Use `customer_use` for real customers. See [Sub-account KYC](/docs/sub-accounts/kyc/overview).
* **Partner child accounts** always complete their own KYC. You start a [KYC session](/docs/partner/api/kyc-sessions) and either email the customer a hosted link or embed the hosted widget in your own onboarding flow. A `kyc.completed` webhook tells you when to unlock calling.
In both models the KYC flow can run inside your product. The customer sees a Vobiz-hosted verification step, similar to a payment gateway popup, and never has to visit the Vobiz Console.
### Phone numbers
Numbers belong to the account that holds the KYC they were bought under, and every customer calls from numbers registered to their own identity. Numbers can be searched and purchased programmatically without the customer ever leaving your platform.
With **sub-accounts** you have two ways to get a number onto a customer:
* **Buy with the main account, then assign.** Purchase from inventory with your main-account credentials, which debits your main balance, then call [assign to sub-account](/docs/account-phone-number/assign-subaccount) with the sub-account's ID. The number now belongs to the sub-account and its calls run under that sub-account's KYC.
* **Let the sub-account buy its own.** The sub-account purchases with its own `auth_id` and `auth_token`. Billing still routes to your main balance, and the number lands on the sub-account with no assign step.
You can move a number back to the main pool with [unassign](/docs/account-phone-number/unassign-subaccount). If the number had a call in the last 15 days, a 15-day cool-off applies before it can be reassigned. Plan number moves between customers with that in mind.
With **partner accounts**, you assign numbers to the child account from the partner view, or the child account buys numbers itself from its own wallet. See [partner numbers](/docs/partner/api/numbers).
A useful habit in both models: create **one trunk per agent or campaign** inside each customer's account. Trunks are a clean filter for cost, connect rate, and which numbers are in play, so you can compare agents without extra tagging.
### CPS and concurrency
This is the biggest practical difference.
With **sub-accounts**, CPS and concurrency are set once on the main account and **pooled** across all sub-accounts. You never pay for capacity per customer, and idle customers lend their headroom to busy ones. The trade-off is that one high-volume customer can consume the pool and leave less for the others. If you run high volumes, build concurrency control into your own campaign manager: queue calls per customer and release them at the rate each customer should get. Every campaign has its own idea of fair share, so this logic belongs on your side.
With **partner accounts**, each child account has **its own** CPS and concurrency limits. You hold a partner pool and [transfer slots](/docs/partner/api/capacity) to a customer, then reclaim them when that customer scales down. A customer's spike never affects anyone else, and you do not need your own concurrency limiter for isolation.
## Which one should you choose?
```mermaid theme={null}
flowchart TD
S([New customer on your platform]) --> Q1{Should Vobiz invoice
this customer directly?}
Q1 -- Yes --> PA[Partner child account]
Q1 -- No --> Q2{Do you want to set your own
pricing and stay in the loop?}
Q2 -- No --> PA
Q2 -- Yes --> Q3{Do they need dedicated CPS / concurrency
that you cannot rate-limit yourself?}
Q3 -- Yes --> PA
Q3 -- No --> SA[Sub-account]
```
**Choose sub-accounts when:**
* You want one Vobiz bill and a single wallet to manage.
* You set your own prices and keep a margin.
* You are fine with pooled CPS and concurrency, or you already limit per-customer throughput in your own dialer.
* You want to stay the single point of contact for your customers.
**Choose partner accounts when:**
* Large customers should be invoiced by Vobiz directly rather than through you.
* Each customer needs CPS and concurrency that no other customer can eat into.
* Customers should own their relationship with Vobiz, including support.
* You still want programmatic control, since you hold each child account's credentials.
**Use both.** A common pattern is sub-accounts for the long tail of small and medium customers, and partner child accounts for a handful of large customers with their own volume commitments. Vobiz supports running both under the same organisation.
## Capacity planning
Default CPS and concurrency limits are sized for getting started. If you are pooling many customers under sub-accounts, or allocating dedicated slots to partner children, you will want more capacity. Higher limits and volume pricing come with a commitment plan, often as a ramp-up over a few months. Contact [support@vobiz.ai](mailto:support@vobiz.ai) with your expected monthly minutes and customer count.
## Next steps
Create a customer\_use sub-account, run KYC, buy a number, and place the first call.
Provision a child account, transfer balance, run a KYC session, and watch CDRs.
Per-document and hosted KYC for customer\_use sub-accounts.
Transfer and reclaim capacity between your pool and a child account.
This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.
