POST /v3/initialize

POST /v3/initialize starts a verification and returns the hosted URL to send the user to. It is 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 here, or
  session_id: string; // hand to the SDK's vycheck({ session }) to embed the flow
};

This page is the guided walkthrough. To see every endpoint and try it out against the live API, use the API Reference. It is 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 are marked secret key only below; sending them with a publishable key returns 400. Keys come in matched test and live pairs. A session started with a test key mints tokens only the test secret key can confirm, and the same goes for live. Use the test pair while you build, then swap both keys together.

Publishable key

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

Secret key

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

Body parameters

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, and as the return destination when the verification has no saved redirect URL.

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>. The redirect URL saved on the verification takes precedence when set.

string

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

string

Secret key only. Target a verification directly instead of running your default one.

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.

string

Secret key only. Attach a verified identity to the person (makes them a member). Fails if that identity is already claimed.

string

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

string

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

string

A non-PII label carried on the session. Use it to correlate sessions with your own analytics.

object

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

Response

string

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

string | null

The minted session id. Pass it to the SDK’s vycheck({ session }) to run the flow in a drawer or inline embed instead of redirecting to url.

{
  "url": "https://app.verifyyou.com/v/abc123",
  "session_id": "sess_abc123"
}

Examples

curl -X POST https://trust.verifyyou.com/v3/initialize \
  -H "Authorization: Bearer sk_test_…" \
  -H "Content-Type: application/json" \
  -d '{ "external_id": "user_123" }'
# => { "url": "https://app.verifyyou.com/v/abc123" }

const res = await fetch("https://trust.verifyyou.com/v3/initialize", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.VY_SK}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    external_id: "user_123", // secret key only; links the session to your user
  }),
});
const { url } = await res.json();
// Redirect the user to `url`.

Errors

Errors return the matching HTTP status and a JSON body with a detail code:

{ "detail": "identifiers_require_secret_key" }

Status	`detail`	Cause
`400`	`identifiers_require_secret_key`	`external_id`, `email`, `phone`, `verification_id`, or `verification_external_id` was sent with a publishable key. Use a secret key.
`401`	`invalid_key_type`	The `Authorization` key isn’t a recognized publishable or secret key.
`401`	`invalid_or_revoked_key`	The key is unknown or has been revoked.
`403`	`config_requires_test_key`	A `config` override was sent with a live key. Inline config is test-only.
`404`	`no_matching_verification`	Couldn’t resolve which verification to run. Pass `verification_id`.
`409`	`external_id_already_exists`	The `external_id` is already bound to a verification.
`422`	`config_incomplete: missing …`	The `config` declares options that aren’t built yet; the message lists them.
`422`	validation error	The request body failed schema validation.

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 run the flow for you, as a redirect, a drawer, or an inline embed:

import { init, vycheck } from "@verifyyou-sdk/client";

init({ publishableKey: "pk_test_…" });
verifyButton.addEventListener("click", () => vycheck());

init() takes the publishable key only. The secret key never belongs in the browser; parameters that need it, like external_id and email, are the reason this server-side endpoint exists.

After the user returns, confirm the token on your backend. Initializing a session doesn’t verify anyone on its own.

Verification processes

SDK and API

Advanced usage

Reference

POST /v3/initialize

Authentication

Publishable key

Secret key

Body parameters

Response

Examples

Errors

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

​Authentication

Publishable key

Secret key

​Body parameters

​Response

​Examples

​Errors

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

Authentication

Body parameters

Response

Examples

Errors

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