Partner Integration 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 supports two ways to initiate KYC. Pick the one that matches your onboarding UX:

Email flow (default, async) - Vobiz emails the customer a link to a hosted KYC widget. They complete verification later from their inbox.
Redirect flow (real-time) - Vobiz returns a widget_url in the response. You redirect the customer to it during signup; their browser comes back to your redirect_url after verification.

Full request/response reference: KYC Sessions API. POST https://api.vobiz.ai/api/v1/partner/kyc-sessions

Email flow

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",
    "flow_type": "email",
    "customer_email": "customer@example.com",
    "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": "a5f8da3c-b47f-40c3-a3e6-d2c9a0f27065",
  "account_auth_id": "MA_XXXXXXXX",
  "customer_email": "customer@example.com",
  "email_dispatched_to": "c***@example.com",
  "kyc_type": null,
  "status": "email_sent",
  "expires_at": "2026-05-28T10:00:00Z",
  "widget_url": null,
  "kyc_link": null,
  "message": "KYC email dispatched successfully"
}

POST /kyc-sessions itself sends the first email, which starts a 30-minute resend cooldown. Calling /resend immediately after creation returns 429. Also, creating a new session for an account_auth_id that already has an active one silently auto-revokes the old session - always act on the most recent session_id. See KYC Sessions for the full edge-case matrix.

Redirect flow

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",
    "flow_type": "redirect",
    "redirect_url": "https://yourapp.com/kyc-complete",
    "webhook_url": "https://yourapp.com/kyc-webhook",
    "expires_in_days": 14
  }'

{
  "session_id": "1a0f7da5-2abb-47bf-a6c3-eb5cff7feda5",
  "account_auth_id": "MA_XXXXXXXX",
  "customer_email": null,
  "email_dispatched_to": null,
  "kyc_type": null,
  "status": "link_ready",
  "expires_at": "2026-05-28T10:00:00Z",
  "widget_url": "https://kyc.vobiz.ai/verify?token=kst_cb1b3fda15c0df5cf58a283e47e9eee148ce0b2b87d7c6693f77296612f58f07",
  "kyc_link": null,
  "message": "KYC session created - redirect your customer to widget_url to begin."
}

A fresh redirect-flow session starts at link_ready (not email_sent). Redirect the customer’s browser to widget_url immediately. After verification, their browser is sent back to:

https://yourapp.com/kyc-complete?session_id=1a0f7da5-…&status=kyc_completed&auth_id=MA_XXXXXXXX

Treat the redirect return params as a UI hint, not proof of completion. Query params can be spoofed. When your redirect_url is hit, confirm the real outcome before unlocking anything - either trust the kyc.completed webhook (below) or call GET /kyc-sessions/{session_id} and check status server-side.

expires_in_days defaults to 7 if omitted. The examples above override it to 14.

Step 4 - Customer completes KYC

The customer completes verification on the Vobiz-hosted widget (either by clicking the email link, or via the redirect URL).

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

Webhook events

Vobiz POSTs JSON to your webhook_url as the session progresses:

kyc.completed - All steps verified. The sub-account’s kyc_status flips to completed.
kyc.failed - Document invalid, name mismatch, or OTP failure. The session terminates.
kyc.session_revoked - You revoked the session (or a newer session auto-revoked it).

A kyc.completed payload echoes your metadata and the verified data:

{
  "event": "kyc.completed",
  "session_id": "1a0f7da5-2abb-47bf-a6c3-eb5cff7feda5",
  "account_auth_id": "MA_XXXXXXXX",
  "kyc_type": "individual",
  "status": "kyc_completed",
  "metadata": { "customer_ref": "TEST_001", "plan": "starter" },
  "verified_data": {
    "pan_type": "individual",
    "pan_name_match": true,
    "completed_steps": ["pan", "aadhaar"]
  }
}

Verify and handle the webhook

Always re-confirm the session server-side before granting access - never trust the POST body alone. Respond 200 fast and process asynchronously so Vobiz doesn’t retry.

from fastapi import FastAPI, Request
import httpx

app = FastAPI()
BASE = "https://api.vobiz.ai/api/v1/partner"
HEADERS = {"X-Auth-ID": "{your_partner_id}", "X-Auth-Token": "{your_auth_token}"}

@app.post("/kyc-webhook")
async def kyc_webhook(req: Request):
    event = await req.json()
    session_id = event["session_id"]

    # Re-fetch the session from Vobiz - the body could be spoofed or stale.
    async with httpx.AsyncClient() as client:
        r = await client.get(f"{BASE}/kyc-sessions/{session_id}", headers=HEADERS)
    session = r.json()

    if session["status"] == "kyc_completed":
        # idempotent: only unlock once
        activate_customer(session["account_auth_id"])
    elif session["status"] == "revoked":
        handle_revoked(session["account_auth_id"])

    return {"ok": True}  # 200 quickly; do heavy work in a background task

Webhook deliveries retry with exponential backoff on any non-2xx response, so make your handler idempotent - the same kyc.completed may arrive more than once.

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

​Authentication Setup

​Step 1 - Create customer account

​Step 2 - Transfer balance to customer

​Step 3 - Initiate KYC session

​Email flow

​Redirect flow

​Step 4 - Customer completes KYC

​Webhook events

​Verify and handle the webhook

​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

Email flow

Redirect flow

Step 4 - Customer completes KYC

Webhook events

Verify and handle the webhook

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