Skip to main content
← Partner API Reference Trigger and manage the customer KYC flow for any sub-account you’ve provisioned. Vobiz supports two delivery modes - async via emailed link, or real-time via in-app redirect - and runs the underlying verification (PAN + Aadhaar OTP for individuals, PAN + GSTIN for companies - no document uploads). Webhook events fire as the session progresses.
All Partner API requests use X-Auth-ID and X-Auth-Token headers. See Authentication for details.

Overview

Flow types

Pick the flow that matches your onboarding UX. The request body, response, and post-verification handoff all differ. Both flows end with the same Vobiz-hosted KYC widget. The widget itself is internal to Vobiz - you do not call its endpoints directly; you either email a link to it, redirect the customer to it, or embed it in an iframe.

Initiate KYC Session - Email Flow

Async flow. Vobiz emails the link to customer_email; the session sits in email_sent until the customer opens it. POST /api/v1/partner/kyc-sessions
Email flow

Response (201)

Subsequent GET calls return the session under the field name id (UUID) - not session_id as in the POST response. Same value, different key. Use whichever the API returned on the request you just made.

Initiate KYC Session - Redirect Flow

Real-time flow. The response contains a widget_url; redirect the customer to it immediately. No email is sent. After the customer finishes, their browser is redirected to redirect_url?session_id=…&status=…&auth_id=… and a webhook fires. POST /api/v1/partner/kyc-sessions
Redirect flow

Response (201)

Theme and embed the KYC widget

Add a theme query parameter to widget_url to match your app. Use the values in lowercase. The theme stays on as the customer moves through the widget.
To show the widget inside your app, load the same URL in an iframe:
Keep the allow value as shown. It gives the widget camera and clipboard access on the host that serves it. Links in KYC emails open in the light theme.
Resend works with email-flow sessions. Redirect-flow sessions have no associated email, so a POST /kyc-sessions/{id}/resend against one returns 400 with message "Resend is not available for redirect-flow sessions - no email is associated with this session."
Only one active session per account_auth_id at a time. Creating a new session (email or redirect) for a sub-account that already has an active session will silently auto-revoke the previous one. The old session’s status flips to revoked at the moment the new one is created.This means: if you call resend / revoke on an “old” session id you stashed earlier, you may get 409 Cannot resend: session is 'revoked' or 409 Session is already in terminal status: 'revoked' because a newer POST replaced it. Always operate on the most recent session_id returned by your most recent POST.

Request body - full field reference

List KYC Sessions

Returns a paginated list of every KYC session you’ve initiated. GET /api/v1/partner/kyc-sessions

Query Parameters

Each session in the sessions[] array contains the fields documented in Session object below.

Get KYC Session

Fetch the current state of a single session - useful for polling if your webhook receiver isn’t reachable. GET /api/v1/partner/kyc-sessions/{session_id}
See Session object for full field reference.

Resend KYC Email

Re-sends the KYC link to the customer’s email. Useful if they lost the email or filtered it as spam. Only valid for email-flow sessions that are still in an active status. POST /api/v1/partner/kyc-sessions/{session_id}/resend
The 30-minute cooldown starts at session creation, not at the first resend. POST /kyc-sessions itself dispatches the first email, so a resend fired immediately after creation returns 429. The 429 response tells you exactly how long to wait:

Revoke KYC Session

Cancels an in-flight session. The hosted link / widget URL stops working immediately and Vobiz fires a kyc.session_revoked webhook. DELETE /api/v1/partner/kyc-sessions/{session_id}

Request Body (optional)

Response (200)

If the session is already in a terminal status, returns 409 with "Session is already in terminal status: '<status>'".

Session lifecycle

Session object

The fields returned on GET /kyc-sessions and GET /kyc-sessions/{session_id}.

Verified data

verified_data accumulates as the customer completes steps. Sample after a successful individual flow:
Sample after a successful company flow:

Webhook events

Vobiz POSTs JSON to your webhook_url as the session progresses:
Webhook deliveries are retried with exponential backoff on non-2xx responses. Respond with 200 OK quickly and process the event asynchronously.

Verification methods

The customer’s PAN determines which flow runs - the partner does not pick it. Neither flow requires the customer to upload documents - Vobiz pulls verification data directly from government APIs.

Errors

All errors share this shape:
Validation errors (422) include a details array with loc / msg / type per field, e.g.: