Skip to main content
POST /v3/initialize starts a verification and returns the hosted URL to redirect the user to. It’s the server-side counterpart to the SDK’s vycheck() — reach for it when you want to mint the session from trusted code, for example to link a known user or bind an identity before the user verifies. 
POST https://trust.verifyyou.com/v3/initialize
Authorization: Bearer <key>
Content-Type: application/json

type InitializeResponse = { url: string }; // redirect the user to `url`
This page is the guided walkthrough. To see every endpoint and try it out against the live API, use the API Reference — it’s generated from the same spec, so it never drifts.

​
Authentication

Accepts a publishable key (pk_…) or a secret key (sk_…). A handful of parameters attach an identity or target a verification directly and therefore require a secret key — they’re marked secret key only below. Sending them with a publishable key returns 400.

Publishable key

From the browser. The SDK uses this. Can pass origin, return_path, start_path, external_tracker, pass_params.

Secret key

From your server. Can pass everything, including the identity and target parameters below.

​
Body parameters

​
origin
string
The domain you start the verification from (e.g. https://yourapp.com). Used to look up which of your verifications to run when verification_id isn’t given.
​
return_path
string
Path on origin the user is redirected back to after verifying (e.g. /verified). We append the result as ?vyt=<token>&vyc=<0|1>. Requires an origin — passed here or taken from the targeted verification.
​
start_path
string
Path on origin the user is coming from. Lets one domain host several verification flows. Requires an origin.
​
verification_id
string
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
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 behavior.
​
email
string
Secret key only. Attach a stable identity to the verification (makes them an account). Fails if that identity is already in use.
​
phone
string
Secret key only. Attach a stable identity to the verification. Fails if that identity is already in use.
​
external_id
string
Secret key only. Link this verification to your own user or record id. See Account linking.
​
external_tracker
string
A non-PII label echoed back in your flow webhooks — correlate funnel events with your own analytics.
​
pass_params
object
Extra query parameters to carry through the flow and re-append to the return URL. Reserved vy* keys are ignored.

​
Response

​
url
string
The hosted verification link with a queued-up session. Redirect the user here.
{ "url": "https://app.verifyyou.com/v/abc123" }

​
Examples

curl -X POST https://trust.verifyyou.com/v3/initialize \
  -H "Authorization: Bearer sk_test_…" \
  -H "Content-Type: application/json" \
  -d '{ "origin": "https://yourapp.com", "return_path": "/verified", "external_id": "user_123" }'
# => { "url": "https://app.verifyyou.com/v/abc123" }  ← redirect the user here

​
Client-side: init() + vycheck()

You don’t have to call this endpoint by hand. In the browser, configure the SDK once with init() and let vycheck() call initialize and redirect for you: 
import { init, vycheck } from "@verifyyou-sdk/client";

init({ publishableKey: "pk_test_…" }); // sets the key + API base on the SDK
await vycheck();
init(config) accepts publishableKey or secretKey, and an optional baseUrl (defaults to production). Use the secret key only on a server.
After the user returns, confirm the token on your backend. Initializing a session doesn’t verify anyone on its own.