Partner API

KYC Verification

The Vobiz Hosted KYC Widget enables white-label partners to seamlessly collect and verify customer identity documents. Using Government-verified databases, Vobiz supports fully automated PAN, Aadhaar (via DigiLocker), and GST verification for Indian customer accounts.

Overview

KYC verification can be completed via two distinct operational flows:

Email Flow (Async)

Vobiz handles the complete delivery lifecycle. Creating an email-flow session sends a secure, uniquely generated KYC link (containing a short-lived token kst_...) directly to the customer's email.

Redirect Flow (Real-Time)

Ideal for embedding verification directly within your own app or portal. No email is sent. Vobiz returns a secure widget_url immediately. Redirect your customer there, and they'll be returned to your specified URL on completion.

KYC Integration Flows

Email Flow Lifecycle Sequence

Partner: Create Session

Create a KYC session with customer account ID

System: Email Dispatched

Vobiz emails secure kyc link (kst_...) to the customer

Customer: Verification Steps

Customer validates token, enters PAN, completes DigiLocker (Individual) or GST (Company)

System: Complete & Webhook

Mark completed and dispatch kyc.completed / kyc.failed webhook events to partner

Redirect Flow Lifecycle Sequence

Partner: Create Session

Create a KYC session with flow_type="redirect" and redirect_url

Partner: Redirect Customer

Instantly redirect customer to the returned widget_url

Customer: Verification Steps

Customer completes verification on the hosted Vobiz widget

System: Redirect & Webhook

Redirect browser to partner redirect_url?session_id=&status=&auth_id= and fire webhook

Partner: Session Management

All partner session management endpoints require X-Auth-ID and X-Auth-Token headers.

Create KYC Session (Email Flow)

POSThttps://api.vobiz.ai/api/v1/partner/kyc-sessions

Generates a secure KYC session. By default, Vobiz dispatches a secure KYC link to the customer email immediately.

cURL Request

curl -X POST \
  "${BASE}/kyc-sessions" \
  -H "X-Auth-ID: YOUR_AUTH_ID" \
  -H "X-Auth-Token: {your_auth_token}" \
  -H "Content-Type: application/json" \
  -d '{
    "account_auth_id": "MA_XXXXXX",
    "flow_type": "email",
    "customer_email": "customer@example.com",
    "webhook_url": "https://your-webhook.site/kyc-events",
    "expires_in_days": 14,
    "reminder_schedule": [
      { "trigger": "days_before_expiry", "value": 3 },
      { "trigger": "days_before_expiry", "value": 1 }
    ],
    "metadata": {
      "customer_ref": "TEST_001",
      "plan": "starter"
    }
  }'

201 Created Response

{
  "session_id": "kycs_9a2b3c4d",
  "status": "email_sent",
  "kyc_type": null,
  "email_dispatched_to": "cu***@example.com",
  "widget_url": null,
  "expires_at": "2026-05-20T10:00:00Z"
}

Create KYC Session (Redirect Flow)

POSThttps://api.vobiz.ai/api/v1/partner/kyc-sessions

When using the redirect flow, customer_email is optional and no email is sent. The widget_url is returned directly in the response.

cURL Request

curl -X POST \
  "${BASE}/kyc-sessions" \
  -H "X-Auth-ID: YOUR_AUTH_ID" \
  -H "X-Auth-Token: {your_auth_token}" \
  -H "Content-Type: application/json" \
  -d '{
    "account_auth_id": "MA_XXXXXX",
    "flow_type": "redirect",
    "webhook_url": "https://your-webhook.site/kyc-events",
    "redirect_url": "https://yourapp.com/kyc-complete",
    "expires_in_days": 14,
    "metadata": {
      "customer_ref": "TEST_001",
      "plan": "starter"
    }
  }'

201 Created Response

{
  "session_id": "kycs_8b3c4d5e",
  "status": "link_ready",
  "kyc_type": null,
  "email_dispatched_to": null,
  "widget_url": "https://kyc.vobiz.ai/token=kst_83bc74d8e92f74ca382f7cda9283f2a1",
  "expires_at": "2026-05-20T10:00:00Z"
}

List KYC Sessions

GEThttps://api.vobiz.ai/api/v1/partner/kyc-sessions

Returns a paginated list of all KYC sessions created under your white-label partner account.

cURL Request

curl -X GET \
  "${BASE}/kyc-sessions?page=1&size=20" \
  -H "X-Auth-ID: YOUR_AUTH_ID" \
  -H "X-Auth-Token: {your_auth_token}"

200 OK Response

{
  "sessions": [
    {
      "id": "kycs_9a2b3c4d",
      "account_auth_id": "MA_XXXXXX",
      "flow_type": "email",
      "status": "email_sent",
      "kyc_type": null,
      "email_dispatched_to": "cu***@example.com",
      "expires_at": "2026-05-20T10:00:00Z"
    }
  ],
  "total": 1
}

Get KYC Session

GEThttps://api.vobiz.ai/api/v1/partner/kyc-sessions/{session_id}

Retrieve status and metadata for a specific KYC session.

cURL Request

curl -X GET \
  "${BASE}/kyc-sessions/kycs_9a2b3c4d" \
  -H "X-Auth-ID: YOUR_AUTH_ID" \
  -H "X-Auth-Token: {your_auth_token}"

200 OK Response

{
  "id": "kycs_9a2b3c4d",
  "account_auth_id": "MA_XXXXXX",
  "status": "in_progress",
  "kyc_type": "individual",
  "expires_at": "2026-05-20T10:00:00Z"
}

Resend KYC Email

POSThttps://api.vobiz.ai/api/v1/partner/kyc-sessions/{session_id}/resend

Resends the secure KYC verification link to the customer email. Rates are limited to 1 email per 30 minutes. Attempting to resend within the cooldown returns a 429 Too Many Requests error.

cURL Request

curl -X POST \
  "${BASE}/kyc-sessions/kycs_9a2b3c4d/resend" \
  -H "X-Auth-ID: YOUR_AUTH_ID" \
  -H "X-Auth-Token: {your_auth_token}"

200 OK Response

{
  "message": "Email resent successfully"
}

Revoke KYC Session

DELETEhttps://api.vobiz.ai/api/v1/partner/kyc-sessions/{session_id}

Immediately revokes the KYC session. The associated secure token link becomes invalid (410 Gone) and fires a kyc.session_revoked webhook event.

cURL Request

curl -X DELETE \
  "${BASE}/kyc-sessions/kycs_9a2b3c4d" \
  -H "X-Auth-ID: YOUR_AUTH_ID" \
  -H "X-Auth-Token: {your_auth_token}" \
  -H "Content-Type: application/json" \
  -d '{
    "reason": "Wrong email address provided"
  }'

200 OK Response

{
  "session_id": "kycs_9a2b3c4d",
  "message": "Session revoked"
}

Webhooks & Events

White-label partners receive real-time HTTP POST callbacks at their configured webhook_url for session lifecycle status changes.

Event Type	Description
kyc.completed	Fires when the verification is fully verified and validated.
kyc.failed	Fires if a verification step fails or is rejected.
kyc.session_revoked	Fires when the partner explicitly deletes/revokes the session.

kyc.completed Webhook Payload

{
  "event": "kyc.completed",
  "session_id": "kycs_9a2b3c4d",
  "account_auth_id": "MA_XXXXXX",
  "kyc_type": "individual",
  "status": "verified",
  "verified_name": "Test Individual",
  "verified_at": "2026-05-06T10:30:00Z"
}

Phone Numbers

Example Flow

Last updated: April 2026Edit this page