Create KYC Session

POST

api

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_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."
}

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

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"
}

​Flow types

​Body fields

​Responses

Authorizations

Path Parameters

Body

Response

Flow types

Body fields

Responses