Skip to main content
POST
/
v3
/
initialize
Initialize a verification session
curl --request POST \
  --url https://api.example.com/v3/initialize \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "origin": "https://yourapp.com",
  "return_path": "/verified",
  "start_path": "/signup",
  "verification_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "verification_external_id": "signup-flow",
  "email": "user@example.com",
  "phone": "<string>",
  "external_id": "user_123",
  "external_tracker": "<string>",
  "pass_params": {}
}
'
{
  "url": "<string>"
}

Authorizations

​
Authorization
string
header
required

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

Body

application/json
​
origin
string | null

Domain you start the verification from (e.g. https://yourapp.com). Used to look up which verification to run when verification_id is not given.

Example:

"https://yourapp.com"

​
return_path
string | null

Path on origin the user is redirected back to after verifying. The result is appended as ?vyt=<token>&vyc=<0|1>. Requires an origin — passed here or taken from the targeted verification.

Example:

"/verified"

​
start_path
string | null

Path on origin the returning user is coming from. Lets a single domain host several verification flows. Requires an origin.

Example:

"/signup"

​
verification_id
string<uuid> | null

Secret key only. Target a verification directly instead of resolving by origin, start_path, and return_path — those then fall back to its saved config.

​
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. Same fallback: origin, start_path, and return_path come from its saved config.

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 — correlate funnel events with your own analytics.

​
pass_params
Pass Params · object

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"