KYC
Create KYC Session
Hand off sub-account KYC to a Vobiz-hosted widget - either email the customer a signed link or redirect them inline. The sub-account-scoped equivalent of the partner KYC Sessions endpoint.
POST
/
api
/
v1
/
sub-accounts
/
{sub_auth_id}
/
kyc-sessions
curl --request POST \
--url https://api.vobiz.ai/api/v1/sub-accounts/{sub_auth_id}/kyc-sessions \
--header 'Content-Type: application/json' \
--header 'X-Auth-ID: <api-key>' \
--header 'X-Auth-Token: <api-key>' \
--data '
{
"account_auth_id": "SA_XXXXXX",
"flow_type": "email"
}
'
{
"session_id": "a5f8da3c-b47f-40c3-a3e6-d2c9a0f27065",
"account_auth_id": "SA_XXXXXX",
"customer_email": "customer@example.com",
"status": "email_sent",
"expires_at": "2026-06-24T19:37:01.316686Z",
"widget_url": null,
"message": "KYC email dispatched successfully"
}
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.
A
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
flow_type | Behavior | Required field |
|---|---|---|
email (default) | Vobiz emails the customer a signed link (from kyc@vobiz.ai, hosted at kyc.vobiz.ai). The session sits in email_sent until they open it. | customer_email |
redirect | The response returns a widget_url directly - redirect the customer’s browser to it. No email is sent. | redirect_url |
Body fields
| Field | Type | Required | Description |
|---|---|---|---|
account_auth_id | string | Yes | The sub-account’s auth_id (SA_…), normally equal to the {sub_auth_id} in the path. |
flow_type | string | Yes | email (default) or redirect. |
customer_email | string | Conditional | Required when flow_type is email. Where the signed link is sent. |
redirect_url | string (URI) | Conditional | Required when flow_type is redirect. The customer is returned here after verification. |
webhook_url | string (URI) | No | HTTPS endpoint Vobiz POSTs the KYC result to. Omit it and no callbacks are sent. |
expires_in_days | integer | No | Days before the link expires. Defaults to 7. |
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
{
"session_id": "a5f8da3c-b47f-40c3-a3e6-d2c9a0f27065",
"account_auth_id": "SA_XXXXXX",
"customer_email": "customer@example.com",
"status": "email_sent",
"expires_at": "2026-06-24T19:37:01.316686Z",
"widget_url": null,
"message": "KYC email dispatched successfully"
}
{
"session_id": "1a0f7da5-2abb-47bf-a6c3-eb5cff7feda5",
"account_auth_id": "SA_XXXXXX",
"customer_email": null,
"status": "link_ready",
"expires_at": "2026-06-24T19:37:01.841263Z",
"widget_url": "https://kyc.vobiz.ai/verify?token=kst_cb1b3fda...",
"message": "Redirect your customer to widget_url to begin."
}
422 is returned when the email flow is missing customer_email, or the redirect flow is missing redirect_url.Authorizations
Your Vobiz account Auth ID
Your Vobiz account Auth Token
Path Parameters
The sub-account's Auth ID.
Example:
"SA_XXXXXX"
Body
application/json
The sub-account's auth_id (typically equal to the path sub_auth_id).
Example:
"SA_XXXXXX"
Available options:
email, redirect Required when flow_type is email.
Example:
"customer@example.com"
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"
HTTPS endpoint VoBiz POSTs the KYC result to. Omit it and no callbacks are sent.
Example:
"https://your-app.example.com/kyc/webhook"
Example:
30
Response
KYC session created
Was this page helpful?
⌘I
curl --request POST \
--url https://api.vobiz.ai/api/v1/sub-accounts/{sub_auth_id}/kyc-sessions \
--header 'Content-Type: application/json' \
--header 'X-Auth-ID: <api-key>' \
--header 'X-Auth-Token: <api-key>' \
--data '
{
"account_auth_id": "SA_XXXXXX",
"flow_type": "email"
}
'
{
"session_id": "a5f8da3c-b47f-40c3-a3e6-d2c9a0f27065",
"account_auth_id": "SA_XXXXXX",
"customer_email": "customer@example.com",
"status": "email_sent",
"expires_at": "2026-06-24T19:37:01.316686Z",
"widget_url": null,
"message": "KYC email dispatched successfully"
}