Example Flow

← Partner Overview A step-by-step integration guide demonstrating the full lifecycle of a customer on your platform - from provisioning and balance transfer to KYC, trunk creation, and CDR monitoring.

Authentication Setup

All Partner API calls require your Master credentials. Store these securely in your backend.

X-Auth-ID: {your_partner_id}
X-Auth-Token: {your_auth_token}

Step 1 - Create customer account

Provision a new SIP-enabled account under your partner umbrella. POST https://api.vobiz.ai/api/v1/partner/accounts

Field	Required	Description
`name`	Yes	Customer’s full name
`email`	Yes	Customer’s email - KYC link is sent here
`phone`	Yes	E.164 format, e.g. `+919876543210`
`password`	Yes	Min 8 chars, must include number and special char
`company`	No	Legal company or business name
`country`	Yes	ISO 2-letter code, e.g. `IN`

curl -X POST \
  "https://api.vobiz.ai/api/v1/partner/accounts" \
  -H "X-Auth-ID: {your_partner_id}" \
  -H "X-Auth-Token: {your_auth_token}" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "John Doe",
    "email": "john@example.com",
    "phone": "+919876543210",
    "password": "SecurePass123!",
    "company": "Acme Corp",
    "country": "IN"
  }'

{
  "auth_id": "MA_XXXXXXXX",
  "auth_token": "<redacted>",
  "name": "John Doe",
  "email": "john@example.com",
  "status": "active",
  "balance": 0.00,
  "currency": "INR",
  "country": "IN",
  "created_at": "2026-03-25T10:00:00Z"
}

Save both auth_id and auth_token. The auth_id is used in every partner API call for this customer. The auth_token is the customer’s own credential - used when calling the Customer API on their behalf.

Step 2 - Transfer balance to customer

When you call the transfer endpoint, Vobiz atomically debits the amount from your partner master balance and credits it to the customer’s wallet.

Your Master Balance - debited by the transfer amount (e.g. -₹500.00).
Customer Wallet - credited by the same amount (e.g. +₹500.00).

POST https://api.vobiz.ai/api/v1/partner/accounts/{customer_auth_id}/transfer-balance

curl -X POST \
  "https://api.vobiz.ai/api/v1/partner/accounts/{customer_auth_id}/transfer-balance" \
  -H "X-Auth-ID: {your_partner_id}" \
  -H "X-Auth-Token: {your_auth_token}" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 500.00,
    "currency": "INR",
    "description": "April recharge"
  }'

{
  "transaction_id": "txn_aabbccdd1234",
  "from_account": "PA_XXXXXXXX",
  "to_account": "MA_XXXXXXXX",
  "amount": 500.00,
  "currency": "INR",
  "description": "April recharge",
  "status": "completed",
  "partner_balance_after": 47750.00,
  "customer_balance_after": 2950.00,
  "timestamp": "2026-03-25T11:00:00Z"
}

Step 3 - Initiate KYC session

Vobiz automatically emails the customer a KYC link. The email is sent to the address on their account. POST https://api.vobiz.ai/api/v1/partner/kyc-sessions

curl -X POST \
  "https://api.vobiz.ai/api/v1/partner/kyc-sessions" \
  -H "X-Auth-ID: {your_partner_id}" \
  -H "X-Auth-Token: {your_auth_token}" \
  -H "Content-Type: application/json" \
  -d '{
    "account_auth_id": "MA_XXXXXXXX",
    "webhook_url": "https://yourapp.com/kyc-webhook",
    "expires_in_days": 14,
    "reminder_schedule": [
      { "trigger": "days_before_expiry", "value": 3 },
      { "trigger": "days_before_expiry", "value": 1 }
    ]
  }'

{
  "session_id": "kycs_aabbccdd1234",
  "status": "email_sent",
  "kyc_type": null,
  "email_dispatched_to": "j***@example.com",
  "expires_at": "2026-05-12T10:00:00Z"
}

Step 4 - Customer completes KYC

The customer clicks the link in their email and completes verification on the Vobiz-hosted widget.

Individual (PAN 4th char = P) - PAN + DOB → Aadhaar via DigiLocker (Govt OTP)
Company (PAN 4th char = C) - PAN + entity name → GSTIN

Webhook events

kyc.completed - All documents verified.
kyc.failed - Document invalid or name mismatch.
kyc.session_revoked - You revoked the session.

Managing KYC sessions

curl -X GET \
  "https://api.vobiz.ai/api/v1/partner/kyc-sessions?page=1&size=20" \
  -H "X-Auth-ID: {your_partner_id}" \
  -H "X-Auth-Token: {your_auth_token}"

curl -X GET \
  "https://api.vobiz.ai/api/v1/partner/kyc-sessions/{session_id}" \
  -H "X-Auth-ID: {your_partner_id}" \
  -H "X-Auth-Token: {your_auth_token}"

curl -X POST \
  "https://api.vobiz.ai/api/v1/partner/kyc-sessions/{session_id}/resend" \
  -H "X-Auth-ID: {your_partner_id}" \
  -H "X-Auth-Token: {your_auth_token}"

curl -X DELETE \
  "https://api.vobiz.ai/api/v1/partner/kyc-sessions/{session_id}" \
  -H "X-Auth-ID: {your_partner_id}" \
  -H "X-Auth-Token: {your_auth_token}" \
  -H "Content-Type: application/json" \
  -d '{ "reason": "Wrong email" }'

Transactions

curl -X GET \
  "https://api.vobiz.ai/api/v1/partner/accounts/{customer_auth_id}/transactions?page=1&per_page=20" \
  -H "X-Auth-ID: {your_partner_id}" \
  -H "X-Auth-Token: {your_auth_token}"

curl -X GET \
  "https://api.vobiz.ai/api/v1/partner/accounts/{customer_auth_id}/transactions?from_date=2026-03-01&to_date=2026-03-31&per_page=100" \
  -H "X-Auth-ID: {your_partner_id}" \
  -H "X-Auth-Token: {your_auth_token}"

curl -X GET \
  "https://api.vobiz.ai/api/v1/partner/accounts/{customer_auth_id}/transactions?transaction_type=recharge&per_page=50" \
  -H "X-Auth-ID: {your_partner_id}" \
  -H "X-Auth-Token: {your_auth_token}"

CDRs (Call History)

Partner view

You (the partner) look up any customer’s call history from your side.

curl -X GET \
  "https://api.vobiz.ai/api/v1/partner/accounts/{customer_auth_id}/cdrs?call_direction=inbound&status=answered&min_duration=10" \
  -H "X-Auth-ID: {your_partner_id}" \
  -H "X-Auth-Token: {your_auth_token}"

Customer view

The customer calls this endpoint using their own credentials.

curl -X GET \
  "https://api.vobiz.ai/api/v1/Account/{customer_auth_id}/cdrs?status=failed&hangup_cause=NO_ANSWER" \
  -H "X-Auth-ID: {customer_auth_id}" \
  -H "X-Auth-Token: {customer_auth_token}"

Phone numbers (partner view)

curl -X GET \
  "https://api.vobiz.ai/api/v1/partner/accounts/{customer_auth_id}/numbers?page=1&per_page=20" \
  -H "X-Auth-ID: {your_partner_id}" \
  -H "X-Auth-Token: {your_auth_token}"

Profile & dashboard

curl -X GET \
  "https://api.vobiz.ai/api/v1/partner/me" \
  -H "X-Auth-ID: {your_partner_id}" \
  -H "X-Auth-Token: {your_auth_token}"

curl -X GET \
  "https://api.vobiz.ai/api/v1/partner/dashboard" \
  -H "X-Auth-ID: {your_partner_id}" \
  -H "X-Auth-Token: {your_auth_token}"

Customer API

These endpoints are called using the customer’s own credentials - not yours as the partner. The auth_id and auth_token are returned when you create the customer account (Step 1).

Base URL - https://api.vobiz.ai/api/v1/Account/{customer_auth_id}/...
Auth headers - X-Auth-ID: {customer_auth_id} + X-Auth-Token: {customer_auth_token}

Inventory Numbers (Browse Available)

Lists phone numbers available to purchase - not yet assigned to any account.

curl -X GET \
  "https://api.vobiz.ai/api/v1/Account/{customer_auth_id}/inventory/numbers?country=IN&page=1&per_page=25" \
  -H "X-Auth-ID: {customer_auth_id}" \
  -H "X-Auth-Token: {customer_auth_token}"

Release a phone number

Returns a number from the customer’s account back to inventory. Permanent - cannot be undone.

curl -X DELETE \
  "https://api.vobiz.ai/api/v1/Account/{customer_auth_id}/numbers/+918071387149" \
  -H "X-Auth-ID: {customer_auth_id}" \
  -H "X-Auth-Token: {customer_auth_token}"

Create a SIP trunk

Vobiz auto-generates a unique SIP domain for the trunk in the format: {trunk_id}.sip.vobiz.ai

curl -X POST \
  "https://api.vobiz.ai/api/v1/Account/{customer_auth_id}/trunks" \
  -H "X-Auth-ID: {customer_auth_id}" \
  -H "X-Auth-Token: {customer_auth_token}" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "My SIP Trunk",
    "trunk_status": "enabled",
    "secure": false,
    "trunk_direction": "outbound",
    "concurrent_calls_limit": 10,
    "cps_limit": 5,
    "transport": "udp"
  }'

{
  "trunk_id": "aabbccdd-1234-5678-90ab-cdef12345678",
  "auth_id": "MA_XXXXXXXX",
  "name": "My SIP Trunk",
  "trunk_domain": "aabbccdd-1234-5678-90ab-cdef12345678.sip.vobiz.ai",
  "trunk_status": "enabled",
  "secure": false,
  "trunk_direction": "outbound",
  "concurrent_calls_limit": 10,
  "cps_limit": 5,
  "transport": "udp",
  "created_at": "2026-03-25T14:09:12Z",
  "updated_at": "2026-03-25T14:09:12Z"
}

Save the trunk_id - it is required for all trunk update, delete, and lookup operations.

Build the full onboarding with an AI agent

End-to-end customer onboarding - create account, transfer balance, fire KYC, all wired up.

Open in Cursor

Endpoints

Documentation Index

​Authentication Setup

​Step 1 - Create customer account

​Step 2 - Transfer balance to customer

​Step 3 - Initiate KYC session

​Step 4 - Customer completes KYC

​Webhook events

​Managing KYC sessions

​Transactions

​CDRs (Call History)

​Partner view

​Customer view

​Phone numbers (partner view)

​Profile & dashboard

​Customer API

​Inventory Numbers (Browse Available)

​Release a phone number

​Create a SIP trunk

​Build the full onboarding with an AI agent

Authentication Setup

Step 1 - Create customer account

Step 2 - Transfer balance to customer

Step 3 - Initiate KYC session

Step 4 - Customer completes KYC

Webhook events

Managing KYC sessions

Transactions

CDRs (Call History)

Partner view

Customer view

Phone numbers (partner view)

Profile & dashboard

Customer API

Inventory Numbers (Browse Available)

Release a phone number

Create a SIP trunk

Build the full onboarding with an AI agent