Create a Subaccount

POST

api

accounts

{auth_id}

sub-accounts

Create a sub-account

curl --request POST \
  --url https://api.vobiz.ai/api/v1/accounts/{auth_id}/sub-accounts/ \
  --header 'Content-Type: application/json' \
  --header 'X-Auth-ID: <api-key>' \
  --header 'X-Auth-Token: <api-key>' \
  --data '
{
  "name": "Customer Co"
}
'

{
  "message": "<string>",
  "sub_account": {
    "name": "<string>",
    "email": null,
    "phone": null,
    "description": null,
    "permissions": null,
    "rate_limit": 123,
    "id": "<string>",
    "parent_account_id": "<string>",
    "parent_auth_id": "<string>",
    "auth_id": "<string>",
    "auth_token": "<string>",
    "api_id": "<string>",
    "email_verified": true,
    "enabled": true,
    "created": "<string>",
    "modified": "<string>",
    "is_active": true,
    "created_at": "<string>",
    "updated_at": "<string>",
    "last_used": null,
    "account": "<string>",
    "resource_uri": "<string>"
  },
  "auth_credentials": {
    "auth_id": "<string>",
    "auth_token": "<string>"
  },
  "tokens": {
    "access_token": "<string>",
    "refresh_token": "<string>",
    "token_type": "<string>",
    "expires_in": 123
  }
}

POST https://api.vobiz.ai/api/v1/accounts/{auth_id}/sub-accounts/

Provision isolated subaccounts under your main account for multi-tenant SaaS applications, reseller models, or departmental resource segregation.

Authentication required:

X-Auth-ID - Your account Auth ID
X-Auth-Token - Your account Auth Token
Content-Type: application/json

Parameters

Field	Type	Required	Description
`name`	string	Yes	A human-readable name for the subaccount. The only required field.
`email`	string	Conditional	Email address for the subaccount. Required when `kyc_mode` is `customer_use` (the KYC link and reminders are sent here). Optional otherwise.
`phone`	string	No	Phone number associated with the subaccount.
`description`	string	No	Description of the sub-account purpose or usage.
`rate_limit`	integer	No	API rate limit for this sub-account (requests per time period). Defaults to `1000` when omitted.
`permissions`	object	No	Permissions object defining what the sub-account can access. Contains boolean fields like `calls` and `cdr`. When omitted, the sub-account inherits the parent’s default access.
`password`	string	No	Login password for the sub-account console. The API credentials (`auth_id` / `auth_token`) are generated regardless and are what you use for REST/telephony calls.
`enabled`	boolean	No	Whether the subaccount is active and enabled for use. Defaults to `true`.
`kyc_mode`	string	No	`personal_use` (default) inherits the parent’s KYC; `customer_use` requires the sub-account to complete its own KYC. `customer_use` requires `email`.
`business_type`	string	No	Legal constitution of the customer: `individual`, `proprietorship`, `private_limited`, `llp`, `partnership`, `public_limited`, `trust`, `society`, `huf`, or `government`. Drives which KYC documents are required — see the document matrix.

Authenticate as the parent. Send your parent main account’s X-Auth-ID / X-Auth-Token; the {auth_id} in the path is your parent (MA_…) account. The sub-account does not have credentials until this call returns them.

Creating a sub-account with kyc_mode: "customer_use" returns it with kyc_calls_blocked: true — the sub-account cannot place calls until it completes KYC. If you omit email while setting customer_use, the request fails with 400. See Sub-Account KYC for the full create → KYC → unblock recipe.

Request

curl -X POST 'https://api.vobiz.ai/api/v1/accounts/{auth_id}/sub-accounts/' \
--header 'X-Auth-ID: {auth_id}' \
--header 'X-Auth-Token: {auth_token}' \
--header 'Content-Type: application/json' \
--data-raw '{
  "name": "Support Team",
  "email": "support@example.com",
  "phone": "+1234567890",
  "description": "Support-facing voice workload",
  "rate_limit": 500,
  "permissions": {
    "calls": true,
    "cdr": true
  },
  "password": "S0pport123!",
  "enabled": true,
  "kyc_mode": "customer_use"
}'

Response Example

Success Response (201 Created)

{
  "message": "Sub-account created successfully",
  "sub_account": {
    "name": "Support Team",
    "email": "support@example.com",
    "phone": "+1234567890",
    "description": "Support-facing voice workload",
    "permissions": {
      "calls": true,
      "cdr": true
    },
    "rate_limit": 500,
    "id": "500001",
    "parent_account_id": "510762",
    "parent_auth_id": "MA_XXXXXXXX",
    "auth_id": "SA_XXXXXXXX",
    "auth_token": "sub_account_auth_token_shown_once",
    "api_id": "aabbccdd-1234-5678-90ab-cdef12345678",
    "email_verified": false,
    "enabled": true,
    "is_active": true,
    "created": "2025-10-22T03:57:35.997500Z",
    "modified": "2025-10-22T03:57:35.997500Z",
    "created_at": "2025-10-22T03:57:35.997500Z",
    "updated_at": "2025-10-22T03:57:35.997500Z",
    "account": "/v1/Account/MA_XXXXXXXX/",
    "resource_uri": "/v1/Account/MA_XXXXXXXX/Subaccount/SA_XXXXXXXX/",
    "last_used": null
  },
  "auth_credentials": {
    "auth_id": "SA_XXXXXXXX",
    "auth_token": "sub_account_auth_token_shown_once"
  },
  "tokens": {
    "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
    "refresh_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
    "token_type": "bearer",
    "expires_in": 1800
  }
}

Success! The response contains three sections:

sub_account - The created sub-account object with all details.
auth_credentials - The sub-account’s own auth_id and auth_token. These are its primary API credentials — used as the X-Auth-ID / X-Auth-Token headers on every REST and telephony API call, exactly like a main account. Save them securely.
tokens - Optional JWT access/refresh tokens for signing the sub-account into the console/dashboard. They are not required to call the REST or telephony API — use the auth_id / auth_token above for that.

Security Note: The auth_token is only returned once during creation. Store it securely - you will not be able to retrieve it again. If lost, you will need to regenerate credentials.

`business_type` and required documents

For a customer_use sub-account, business_type sets which KYC documents the sub-account must clear before kyc_calls_blocked flips to false:

`business_type`	Typical documents to verify
`individual`, `proprietorship`, `huf`	PAN + Aadhaar (via DigiLocker)
`private_limited`, `public_limited`, `llp`, `partnership`	PAN + GST and/or CIN
`trust`, `society`, `government`	PAN + supporting registration (CIN/GST as applicable)

You can set business_type at creation or later via Update. See Sub-Account KYC for the per-document endpoints.

Common errors

Status	Cause
`400`	`kyc_mode: "customer_use"` set without an `email`.
`401`	Missing or wrong `X-Auth-ID` / `X-Auth-Token`, or the path uses the wrong casing (`/accounts/`, plural and lowercase).
`404`	The `{auth_id}` in the path is not a main account you own.

Authorizations

X-Auth-ID

string

header

required

Your Vobiz account Auth ID

X-Auth-Token

string

header

required

Your Vobiz account Auth Token

Path Parameters

auth_id

string

required

Your account Auth ID

Example:

"MA_XXXXXX"

Body

application/json

name

string

required

Human-readable name for the sub-account.

string<email>

Required when kyc_mode is customer_use.

password

string

kyc_mode

enum<string>

default:personal_use

personal_use inherits parent KYC. customer_use requires the sub-account to complete its own KYC and requires email.

Available options:

personal_use,

customer_use

business_type

enum<string>

Legal constitution of the customer. Drives which KYC documents are required.

Available options:

individual,

proprietorship,

private_limited,

llp,

partnership,

public_limited,

trust,

society,

huf,

government

enabled

boolean

Response

Success

message

string

required

sub_account

object

required

Show child attributes

auth_credentials

object

required

Show child attributes

tokens

object

required

Show child attributes

The Subaccount Object

Retrieve a Subaccount

Create a sub-account

curl --request POST \
  --url https://api.vobiz.ai/api/v1/accounts/{auth_id}/sub-accounts/ \
  --header 'Content-Type: application/json' \
  --header 'X-Auth-ID: <api-key>' \
  --header 'X-Auth-Token: <api-key>' \
  --data '
{
  "name": "Customer Co"
}
'

{
  "message": "<string>",
  "sub_account": {
    "name": "<string>",
    "email": null,
    "phone": null,
    "description": null,
    "permissions": null,
    "rate_limit": 123,
    "id": "<string>",
    "parent_account_id": "<string>",
    "parent_auth_id": "<string>",
    "auth_id": "<string>",
    "auth_token": "<string>",
    "api_id": "<string>",
    "email_verified": true,
    "enabled": true,
    "created": "<string>",
    "modified": "<string>",
    "is_active": true,
    "created_at": "<string>",
    "updated_at": "<string>",
    "last_used": null,
    "account": "<string>",
    "resource_uri": "<string>"
  },
  "auth_credentials": {
    "auth_id": "<string>",
    "auth_token": "<string>"
  },
  "tokens": {
    "access_token": "<string>",
    "refresh_token": "<string>",
    "token_type": "<string>",
    "expires_in": 123
  }
}

​Parameters

​Request

​Response Example

​business_type and required documents

​Common errors

Authorizations

Path Parameters

Body

Response

Parameters

Request

Response Example

`business_type` and required documents

Common errors