Walk through a full Vobiz partner integration - provision a customer, transfer balance, complete KYC, create a SIP trunk, and monitor live CDRs end-to-end.
← Partner OverviewA 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.
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.
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
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.
{ "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:
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.
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, Requestimport httpxapp = 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.
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}/...
