/v3/initialize

POST Secret key. Returns the session_id your frontend opens with vycheck({ session }), and the hosted url if you would rather redirect yourself.

Body

string (uuid)

Which verification to run. Omit for your default.

string

Where the person lands when done, with ?vyt=<token>&vyc=<0|1> appended. Overrides the URL saved on the verification. Absolute https; http allowed on localhost and private addresses.

string

Your id for this run. Duplicates are reported against it. A different id than the person’s earlier pass always runs a fresh check, even inside the skip window.

string

Bind the run to this email. The flow cannot collect a different one. One of email or phone.

string

Bind the run to this phone. Same rules.

string

Your id for the uniqueness pool this run belongs to, so one verification can be reused across separate groups. Judged only against passes carrying the same group; omit to judge against all of them. Keep external_id per person rather than per group. 1 to 255 characters. See Groups.

string[]

Other groups whose history also counts against this run. A prior pass in an included group blocks or flags exactly as a pass in the run’s own group would, following the verification’s settings; the run still settles into its own group. Does nothing without group, since an ungrouped run is judged against everything already. Up to 50 ids, each 1 to 255 characters. See Groups.

object<string, string>

Extra query params echoed onto the return URL. vy* names are ignored.

object

Test key only. Per-run config override, used verbatim, never merged.

boolean

Return to redirect_url the instant an approved check settles, instead of showing the result screen with a return button. Works with any key. Overlays the verification’s saved setting for this run only. Ignored by invite links.

Response

string

Open it with vycheck({ session }).

string

Hosted link with the run queued up.

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

Errors

Status	`detail`	When
`400`	`one_identifier_only`	Both `email` and `phone`.
`400`	`identifier_unrecognized`	Not a parseable email or phone.
`400`	`invalid_redirect_url`	Not absolute, or not `https` off localhost.
`400`	`verification_requires_identifier`	The verification is set to “provided by you” and none was sent.
`400`	`identifiers_require_secret_key`	A deprecated publishable key was used with identity or targeting fields.
`400`	`invalid_verification_config`	The verification’s stored config does not compile.
`403`	`config_requires_test_key`	`config` with a live key.
`404`	`no_matching_verification`	Not on your account.
`409`	`link_not_active`	The verification runs on invites, so it has no code door.
`409`	`method_not_runnable`	The verification runs on one-time passwords and its code pool has not been provisioned yet.

Example

curl -X POST https://trust.verifyyou.com/v3/initialize \
  -H "Authorization: Bearer sk_test_…" -H "Content-Type: application/json" \
  -d '{ "verification_id": "<id>", "redirect_url": "https://yourapp.com/verified", "external_id": "acct_8f21" }'

Deprecated and still accepted (see the OpenAPI spec): verification_external_id, external_tracker, expire_in_days, and the invite_id response field.

Integrating

Server API

Browser SDK

Reference

Body

Response

Errors

Example

​Body

​Response

​Errors

​Example

Body

Response

Errors

Example