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 tocustomer_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 awidget_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 atheme 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.
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.
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
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}
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
Revoke KYC Session
Cancels an in-flight session. The hosted link / widget URL stops working immediately and Vobiz fires akyc.session_revoked webhook.
DELETE /api/v1/partner/kyc-sessions/{session_id}
Request Body (optional)
Response (200)
409 with "Session is already in terminal status: '<status>'".
Session lifecycle
Session object
The fields returned onGET /kyc-sessions and GET /kyc-sessions/{session_id}.
Verified data
verified_data accumulates as the customer completes steps. Sample after a successful individual flow:
Webhook events
Vobiz POSTs JSON to yourwebhook_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:422) include a details array with loc / msg / type per field, e.g.:
Related
- Partner Integration Flow - end-to-end walkthrough including KYC.
- Create Customer Account -
account_auth_idis returned here.