Skip to main content
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.
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_typeBehaviorRequired 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
redirectThe response returns a widget_url directly — redirect the customer’s browser to it. No email is sent.redirect_url

​
Body fields

FieldTypeRequiredDescription
account_auth_idstringYesThe sub-account’s auth_id (SA_…), normally equal to the {sub_auth_id} in the path.
flow_typestringYesemail (default) or redirect.
customer_emailstringConditionalRequired when flow_type is email. Where the signed link is sent.
redirect_urlstring (URI)ConditionalRequired when flow_type is redirect. The customer is returned here after verification.
webhook_urlstring (URI)NoHTTPS endpoint Vobiz POSTs the KYC result to. Omit it and no callbacks are sent.
expires_in_daysintegerNoDays 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."
}
A 422 is returned when the email flow is missing customer_email, or the redirect flow is missing redirect_url.

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