Vobiz Logo
Vobiz
|API Documentation
Console

Sub-Account Management

Create and manage sub-accounts for multi-tenant SaaS applications or reseller models. Each sub-account has its own credentials and isolated resources while being managed by the parent account.

Important Notes

  • Sub-account endpoints use /accounts/ (plural) with trailing slash
  • Sub-account IDs have prefix SA_ vs main accounts with MA_
  • Only main accounts can create and manage sub-accounts
  • Sub-accounts have their own auth credentials and JWT tokens

Create Sub-Account

POST/api/v1/accounts/{accountId}/sub-accounts/

Create a sub-account under your main account. The sub-account will have its own credentials and can be used to isolate resources for different customers or departments.

▶HTTP Headers
Host:api.vobiz.ai
Content-Type:application/json
Authorization:Bearer {{accessToken}}

About This Endpoint

Provision isolated sub-accounts under your main account for multi-tenant SaaS applications, reseller models, or departmental resource segregation. Each sub-account receives unique authentication credentials (auth_id and auth_token), operates with complete resource isolation from other sub-accounts, and can independently manage its own trunks, phone numbers, and balances. The sub-account ID is prefixed with SA_ distinguishing it from main accounts, and credentials are generated immediately for programmatic API access.

Sub-Account Capabilities
  • Complete resource isolation with dedicated auth credentials for secure multi-tenancy
  • Independent management of trunks, numbers, CDRs, and balances per sub-account
  • Parent account retains full administrative control over all sub-account operations
Common Use Cases
  • SaaS platforms creating isolated environments for each enterprise customer
  • Reseller businesses providing white-labeled telephony services to end customers
  • Large organizations segregating resources by department or geographic region
Request Body
{
  "name": "Support Team",
  "description": "Support-facing voice workload",
  "rate_limit": 500,
  "permissions": {
    "calls": true,
    "cdr": true
  },
  "password": "S@pport123!"
}

Response Example

Success Response (201 Created)
{
  "sub_account": {
    "id": "SA_3310KXXM",
    "parent_account_id": "MA_2210JXXN",
    "name": "Customer Sub-Account",
    "description": "Sub-account for enterprise customer",
    "auth_id": "newAuthId123456789",
    "auth_token": "newAuthToken987654321...",
    "is_active": true,
    "created_at": "2025-10-12T10:30:00.000Z"
  }
}

Success! Save the auth_id andauth_token - these are the API credentials for this sub-account.

List Sub-Accounts

GET/api/v1/accounts/{accountId}/sub-accounts/

Retrieve all sub-accounts under your main account with their status and metadata.

▶HTTP Headers
Host:api.vobiz.ai
Authorization:Bearer {{accessToken}}

About This Endpoint

Retrieve the complete inventory of sub-accounts created under your main account, including names, descriptions, active status, and creation timestamps. The response provides a hierarchical view of your account structure, enabling management dashboards to display organizational structure or customer portfolios. Each sub-account entry includes basic metadata without sensitive credential information, making this endpoint safe for general administrative interfaces. The total count facilitates pagination and capacity planning for multi-tenant platforms.

Response Information
  • Array of all sub-accounts with IDs, names, descriptions, and active status
  • Creation and update timestamps for audit trails and activity monitoring
  • Total count for pagination and dashboard summary statistics
Common Use Cases
  • Building admin dashboards showing organizational hierarchy and customer accounts
  • Generating customer lists for billing, reporting, or account management portals
  • Auditing sub-account creation and monitoring platform growth metrics

Response Example

Success Response (200 OK)
{
  "sub_accounts": [
    {
      "id": "SA_3310KXXM",
      "parent_account_id": "MA_2210JXXN",
      "name": "Customer Sub-Account",
      "description": "Sub-account for enterprise customer",
      "is_active": true,
      "created_at": "2025-10-12T10:30:00.000Z",
      "updated_at": "2025-10-12T10:30:00.000Z"
    },
    {
      "id": "SA_4420LXXP",
      "parent_account_id": "MA_2210JXXN",
      "name": "Department Sub-Account",
      "description": "Sub-account for sales department",
      "is_active": true,
      "created_at": "2025-10-11T14:20:00.000Z",
      "updated_at": "2025-10-11T14:20:00.000Z"
    }
  ],
  "total": 2
}

Get Sub-Account Details

GET/api/v1/accounts/{accountId}/sub-accounts/{subAccountId}

Get detailed information about a specific sub-account including its credentials and configuration.

▶HTTP Headers
Host:api.vobiz.ai
Authorization:Bearer {{accessToken}}

About This Endpoint

Fetch comprehensive details for a specific sub-account including authentication credentials, operational status, and resource usage summary metadata. The response includes the auth_id (but not the auth_token for security), enabling credential lookup if needed for customer support or integration troubleshooting. Extended metadata provides aggregated statistics showing total trunks, phone numbers, and last activity timestamp—valuable for monitoring sub-account utilization without querying individual resource endpoints separately.

Detailed Information
  • Complete sub-account configuration including auth_id, name, description, status
  • Resource usage summary: total trunks, numbers provisioned, and activity timestamps
  • Parent-child relationship information linking sub-account to main account
Common Use Cases
  • Customer support lookups to verify sub-account configuration and credentials
  • Monitoring sub-account activity and resource utilization for capacity planning
  • Auditing sub-account settings before making configuration changes

Response Example

Success Response (200 OK)
{
  "id": "SA_3310KXXM",
  "parent_account_id": "MA_2210JXXN",
  "name": "Customer Sub-Account",
  "description": "Sub-account for enterprise customer",
  "auth_id": "authId123456789",
  "is_active": true,
  "created_at": "2025-10-12T10:30:00.000Z",
  "updated_at": "2025-10-12T10:30:00.000Z",
  "metadata": {
    "total_trunks": 5,
    "total_numbers": 10,
    "last_active": "2025-10-12T15:45:00.000Z"
  }
}

Update Sub-Account

PUT/api/v1/accounts/{accountId}/sub-accounts/{subAccountId}

Update sub-account information such as name, description, or active status.

▶HTTP Headers
Host:api.vobiz.ai
Content-Type:application/json
Authorization:Bearer {{accessToken}}

About This Endpoint

Modify sub-account metadata and operational status without affecting authentication credentials or resource associations. Update name and description fields for organizational clarity as customer names change or account purposes evolve. Most critically, toggle the is_active flag to suspend or reactivate sub-accounts—deactivation immediately prevents all API access and call processing for the sub-account while preserving all data and configuration for potential future reactivation. Changes apply instantly without requiring credential regeneration.

Modifiable Fields
  • Name and description for organizational updates and rebranding scenarios
  • is_active status to suspend/reactivate sub-accounts without deleting resources
  • Changes preserve credentials and resource associations—only metadata updates
Status Management
  • Setting is_active=false immediately blocks all sub-account API calls and trunk usage
  • Suspended sub-accounts retain all data—trunks, numbers, CDRs remain intact
  • Reactivation (is_active=true) instantly restores full operational capabilities
Request Body
{
  "name": "Updated Sub-Account Name",
  "description": "Updated description",
  "is_active": true
}

Response Example

Success Response (200 OK)
{
  "message": "Sub-account updated successfully",
  "sub_account": {
    "id": "SA_3310KXXM",
    "name": "Updated Sub-Account Name",
    "description": "Updated description",
    "is_active": true,
    "updated_at": "2025-10-12T16:00:00.000Z"
  }
}

Delete Sub-Account

DELETE/api/v1/accounts/{accountId}/sub-accounts/{subAccountId}

Permanently delete a sub-account and all its associated resources.

▶HTTP Headers
Host:api.vobiz.ai
Authorization:Bearer {{accessToken}}

Warning: Deleting a sub-account is permanent and will remove all associated resources (trunks, numbers, CDRs). This action cannot be undone.

About This Endpoint

Permanently and irreversibly delete a sub-account along with all associated resources including SIP trunks, phone numbers, call detail records, and transaction history. The operation performs cascading deletion across all resource tables, invalidates authentication credentials immediately, and returns a detailed summary of deleted resources for audit documentation. This destructive action cannot be reversed—there is no recovery mechanism once deletion completes. Consider deactivating (is_active=false) instead if temporary suspension is needed.

Cascading Deletion
  • Removes all trunks, terminating active calls and deregistering from Kamailio
  • Releases all phone numbers back to Twilio inventory without prorated refunds
  • Deletes all CDR history and transaction records permanently from billing database
Safety Recommendations
  • Export critical data (CDRs, billing records) before deletion—no recovery possible
  • Verify no active calls or important phone numbers before proceeding
  • Consider suspension (is_active=false) as non-destructive alternative for disputes

Response Example

Success Response (200 OK)
{
  "message": "Sub-account deleted successfully",
  "deleted_resources": {
    "trunks": 5,
    "phone_numbers": 10,
    "cdr_records": 1250
  }
}

Regenerate Sub-Account Credentials

POST/api/v1/accounts/{accountId}/sub-accounts/{subAccountId}/regenerate-credentials

Generate new auth credentials for a sub-account if the current ones are compromised. Old credentials will be invalidated immediately.

▶HTTP Headers
Host:api.vobiz.ai
Content-Type:application/json
Authorization:Bearer {{accessToken}}

About This Endpoint

Generate fresh authentication credentials for a sub-account when the current auth_id and auth_token are compromised, leaked, or require rotation for security compliance. The operation immediately invalidates all existing credentials and JWT tokens, generating entirely new auth_id and auth_token values returned in the response. This atomic credential rotation ensures no overlap period where both old and new credentials work simultaneously—the instant this endpoint returns successfully, only the new credentials are valid.

Credential Rotation Process
  • Generates completely new auth_id and auth_token with cryptographically random values
  • Immediately invalidates previous credentials—old tokens fail authentication instantly
  • All active JWT sessions for sub-account are revoked, requiring re-authentication
Security Best Practices
  • Save new credentials immediately—they're returned once and cannot be retrieved later
  • Update all applications and integrations with new credentials before invalidation
  • Use this for security incidents, periodic rotation policies, or customer support resets

Response Example

Success Response (200 OK)
{
  "message": "Credentials regenerated successfully",
  "auth_credentials": {
    "auth_id": "newAuthId999888777",
    "auth_token": "newAuthToken777888999abcdef..."
  },
  "previous_credentials_invalidated": true
}

Important: Save the new credentials immediately. The old auth_id and auth_token will stop working as soon as this operation completes.

Sub-Account Use Cases

Multi-Tenant SaaS

Create a sub-account for each customer. Each customer gets isolated resources and their own API credentials for programmatic access.

Reseller Model

Create sub-accounts for resellers who manage their own customers. Track usage and billing separately per sub-account.

Department Isolation

Create sub-accounts for different departments (Sales, Support, Operations). Each department gets their own trunks and phone numbers.

Development/Staging

Create sub-accounts for dev, staging, and production environments. Test changes in isolation without affecting production.

Postman Guide
SIP Trunks