Skip to main content
POST
Initialize a verification session

Authorizations

Authorization
string
header
required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Body

application/json
verification_id
string<uuid> | null

Secret key only. Target a verification directly instead of running the company's default verification.

verification_external_id
string | null

Secret key only. Target a verification by your own external id for it (set when the verification was created), as an alternative to verification_id.

Example:

"signup-flow"

email
string | null

Secret key only. Attach a stable identity to the verification. Fails if that identity is already in use.

Example:

"user@example.com"

phone
string | null

Secret key only. Attach a stable identity to the verification. Fails if that identity is already in use.

external_id
string | null

Secret key only. Link this verification to your own user or record id.

Example:

"user_123"

external_tracker
string | null

Non-PII label echoed back in the flow webhook payload. Use it to correlate funnel events with your own analytics.

pass_params
Pass Params · object | null

Extra query params to carry through the flow and append to the return URL. Reserved vy* keys are ignored.

Response

Successful Response

url
string
required

Hosted verification link with a queued-up session. Redirect the user here.

Example:

"https://app.verifyyou.com/v/abc123"

session_id
string | null

The minted session id. Pass it to the SDK's vycheck({ session }) to run the flow in an embed instead of redirecting to url.