Sub-Account Onboarding Flow

This walkthrough provisions a customer_use sub-account from scratch - create → KYC → number → first call - and is explicit about which credentials to use at each step. Base URL: https://api.vobiz.ai/api/v1

The one rule that prevents most of the confusion

Two credential pairs are in play. Keep them straight:

Credential	What it is	Used for
Parent `X-Auth-ID` / `X-Auth-Token`	Your main account (`MA_…`) API key	All provisioning & administration - create the sub-account, run its KYC, buy numbers, assign/unassign numbers. The `{sub_auth_id}` in the URL identifies which sub-account you act on.
Sub-account `auth_id` / `auth_token`	The sub-account’s own API key (`SA_…`), returned once at creation	The sub-account’s runtime usage - placing/receiving calls, pulling its own CDRs and recordings. Hand this to your customer.

Rule of thumb: if you are setting up the sub-account, authenticate as the parent. Once it’s live, the sub-account authenticates as itself to use the service.

KYC is not an exception. Sub-account KYC endpoints authenticate with the parent’s X-Auth-ID / X-Auth-Token; the sub-account is identified by {sub_auth_id} in the path.

Path casing is significant. Note /accounts/ and /sub-accounts/ (sub-account CRUD + KYC), /account/ (assign to sub-account), and /Account/ (inventory + purchase + calls). The wrong casing returns 401/404 even with valid credentials.

The flow

Create the customer sub-account - parent credentials

A customer that must be KYC’d in its own name is a customer_use sub-account. It requires an email and starts call-blocked until KYC passes.

cURL

curl -X POST "https://api.vobiz.ai/api/v1/accounts/{parent_auth_id}/sub-accounts/" \
  -H "X-Auth-ID: {parent_auth_id}" \
  -H "X-Auth-Token: {parent_auth_token}" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Acme Corp",
    "email": "owner@acme.com",
    "password": "Acme@Secure123",
    "kyc_mode": "customer_use",
    "business_type": "private_limited"
  }'

Response (201) - save the sub-account’s own credentials; auth_token is shown once:

{
  "sub_account": { "id": "SA_67401KW8", "kyc_mode": "customer_use", "kyc_calls_blocked": true },
  "auth_credentials": { "auth_id": "{sub_auth_id}", "auth_token": "{sub_auth_token}" },
  "tokens": { "access_token": "eyJ…", "refresh_token": "eyJ…", "token_type": "bearer", "expires_in": 1800 }
}

auth_credentials → the sub-account’s key (used in the final step).
tokens (JWT) are optional - only for console/dashboard sign-in, not the REST/telephony API.
kyc_calls_blocked: true → the sub-account cannot place calls yet.

Complete KYC - parent credentials

All KYC endpoints live under /sub-accounts/{sub_auth_id}/kyc/… and authenticate as the parent. Run the documents the entity needs (PAN + GST/CIN for companies; PAN + Aadhaar via DigiLocker for individuals), then poll status.

Verify PAN

curl -X POST "https://api.vobiz.ai/api/v1/sub-accounts/{sub_auth_id}/kyc/verify-pan" \
  -H "X-Auth-ID: {parent_auth_id}" \
  -H "X-Auth-Token: {parent_auth_token}" \
  -H "Content-Type: application/json" \
  -d '{ "pan": "ABCDE1234F" }'

Verify GST

curl -X POST "https://api.vobiz.ai/api/v1/sub-accounts/{sub_auth_id}/kyc/verify-gst" \
  -H "X-Auth-ID: {parent_auth_id}" \
  -H "X-Auth-Token: {parent_auth_token}" \
  -H "Content-Type: application/json" \
  -d '{ "gstin": "29ABCDE1234F1Z5" }'

Poll status

curl "https://api.vobiz.ai/api/v1/sub-accounts/{sub_auth_id}/kyc/status" \
  -H "X-Auth-ID: {parent_auth_id}" \
  -H "X-Auth-Token: {parent_auth_token}"

{
  "sub_account_id": "SA_67401KW8",
  "kyc_mode": "customer_use",
  "business_type": "private_limited",
  "overall_status": "verified",
  "kyc_calls_blocked": false,
  "verifications": {
    "pan": "verified",
    "gst": "verified",
    "aadhaar": "not_started",
    "cin": "not_started"
  }
}

When kyc_calls_blocked flips to false, the sub-account may place calls. overall_status is the aggregate (not_started / pending / verified / failed); verifications holds the per-document state.

Building the integration first? Use the test-mode mirror at /sub-accounts/test/{sub_auth_id}/kyc/… with magic inputs (TESTSUCCESS0001 → verified, TESTFAIL0001 → failed, TESTPENDING001 → pending). Same parent auth, no real documents, no provider calls.

Buy a number - parent credentials

Browse inventory, then purchase. Buying with the parent puts the number in the parent’s pool, ready to assign in the next step. Billing for an SA_ purchase always routes to the parent MA_.

Find a number

curl "https://api.vobiz.ai/api/v1/Account/{parent_auth_id}/inventory/numbers" \
  -H "X-Auth-ID: {parent_auth_id}" \
  -H "X-Auth-Token: {parent_auth_token}"

Purchase it

curl -X POST "https://api.vobiz.ai/api/v1/Account/{parent_auth_id}/numbers/purchase-from-inventory" \
  -H "X-Auth-ID: {parent_auth_id}" \
  -H "X-Auth-Token: {parent_auth_token}" \
  -H "Content-Type: application/json" \
  -d '{ "e164": "+919876543210" }'

Purchasing debits the parent’s balance (setup fee + monthly fee).

Link the number to the sub-account - parent credentials

Assign a parent-pool DID to the sub-account. URL-encode + as %2B in the path; name the sub-account in the body via sub_account_id.

cURL

curl -X POST "https://api.vobiz.ai/api/v1/account/{parent_auth_id}/numbers/%2B919876543210/assign-subaccount" \
  -H "X-Auth-ID: {parent_auth_id}" \
  -H "X-Auth-Token: {parent_auth_token}" \
  -H "Content-Type: application/json" \
  -d '{ "sub_account_id": "{sub_auth_id}" }'

The number now belongs to the sub-account.

Moving a number back to the parent pool is subject to a 15-day cool-off if it had a call in the last 15 days. See Unassign DID.

The sub-account places a call - sub-account credentials

Now switch credentials. The sub-account (or your customer) authenticates as itself using the auth_id / auth_token from Step 1.

cURL

curl -X POST "https://api.vobiz.ai/api/v1/Account/{sub_auth_id}/Call/" \
  -H "X-Auth-ID: {sub_auth_id}" \
  -H "X-Auth-Token: {sub_auth_token}" \
  -H "Content-Type: application/json" \
  -d '{
    "from": "+919876543210",
    "to": "+919812345678",
    "answer_url": "https://your-app.example.com/answer.xml"
  }'

This succeeds only when kyc_calls_blocked is false (Step 2 complete).

Alternative: let the sub-account buy its own number

Instead of Steps 3–4, the sub-account can purchase directly with its own auth_id / auth_token (billing still routes to the parent MA_). The number lands directly on the sub-account - no separate assign step:

cURL

curl -X POST "https://api.vobiz.ai/api/v1/Account/{sub_auth_id}/numbers/purchase-from-inventory" \
  -H "X-Auth-ID: {sub_auth_id}" \
  -H "X-Auth-Token: {sub_auth_token}" \
  -H "Content-Type: application/json" \
  -d '{ "e164": "+919876543210" }'

Auth cheat-sheet

Step	Operation	Endpoint	Auth
1	Create sub-account	`POST /accounts/{auth_id}/sub-accounts/`	Parent
2	Verify PAN / GST / CIN / DigiLocker	`POST /sub-accounts/{sub_auth_id}/kyc/…`	Parent
2	KYC status	`GET /sub-accounts/{sub_auth_id}/kyc/status`	Parent
3	List inventory	`GET /Account/{auth_id}/inventory/numbers`	Parent
3	Buy number	`POST /Account/{auth_id}/numbers/purchase-from-inventory`	Parent
4	Assign to sub-account	`POST /account/{auth_id}/numbers/{e164}/assign-subaccount`	Parent
4	Unassign (15-day cool-off)	`DELETE /account/{auth_id}/numbers/{e164}/assign-subaccount`	Parent
5	Place a call	`POST /Account/{auth_id}/Call/`	Sub-account
alt	Sub buys directly	`POST /Account/{auth_id}/numbers/purchase-from-inventory`	Sub-account

TL;DR: Parent credentials for setup (Steps 1–4); the sub-account’s own credentials for usage (Step 5 onward).

​The one rule that prevents most of the confusion

​The flow

​Alternative: let the sub-account buy its own number

​Auth cheat-sheet

The one rule that prevents most of the confusion

The flow

Alternative: let the sub-account buy its own number

Auth cheat-sheet