Skip to main content
POST
Creates a Vobiz-hosted KYC session for the sub-account. Instead of driving each verification step yourself, you hand the customer off to the Vobiz-hosted KYC widget.
Authenticate with your parent main account’s X-Auth-ID and X-Auth-Token - the same credentials used everywhere else in the API.

Flow types

Body fields

This is the sub-account–scoped equivalent of the partner-level KYC Sessions endpoint. For session lifecycle, webhook events, and the verified_data shape, see that page - the hosted widget and status model are the same. The partner endpoint additionally accepts reminder_schedule and metadata; see the email and redirect flow walkthroughs for how those carry through to webhook payloads.

Responses

A 422 is returned when the email flow is missing customer_email, or the redirect flow is missing redirect_url.

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.

Authorizations

X-Auth-ID
string
header
required

Your Vobiz account Auth ID

X-Auth-Token
string
header
required

Your Vobiz account Auth Token

Path Parameters

sub_auth_id
string
required

The sub-account's Auth ID.

Example:

"SA_XXXXXX"

Body

application/json
account_auth_id
string
required

The sub-account's auth_id (typically equal to the path sub_auth_id).

Example:

"SA_XXXXXX"

flow_type
enum<string>
default:email
required
Available options:
email,
redirect
customer_email
string<email>

Required when flow_type is email.

Example:

"customer@example.com"

redirect_url
string<uri>

Required when flow_type is redirect. After verification the customer's browser is sent to this URL.

Example:

"https://your-app.example.com/kyc/done"

webhook_url
string<uri>

HTTPS endpoint Vobiz POSTs the KYC result to. Omit it and no callbacks are sent.

Example:

"https://your-app.example.com/kyc/webhook"

expires_in_days
integer
default:7
Example:

30

Response

KYC session created