Account linking

By default a person you verify is anonymous, recognized only by the device ID in their browser. Account linking ties the verification to your own record and, optionally, binds a durable identity: a claim to their own face record, portable across devices and browsers. You link at POST /v3/initialize, from your server, with a secret key.

Link your own record with `external_id`

Pass external_id to associate the session with a record on your side. Duplicates are reported against it, so one person claiming to be two of your records surfaces as duplicate_account when you confirm.

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", // your id for this person
  }),
});
const { url } = await res.json();
// open the session with vycheck({ session }) or redirect to `url`

Bind an identity with `phone` / `email`

Pass a phone or email to bind the person to a verified identifier. The identity becomes their claim to their face record, so their verified uniqueness travels across devices, browsers, and every product you run on VerifyYou. The flow challenges the identifier you supply with a one-time code, and the person can’t swap it for a different one.

{
  "external_id": "user_123",
  "phone": "+12105550142"
}

An identity is one human. If the phone or email you bind is already claimed by a different face, the run settles denied with the finding in reasons (for example identity_mismatch or duplicate_account). Route the person to sign in and re-assert their existing claim rather than creating a duplicate.

Reading it back

Confirm the token as usual; findings against your linked record arrive in reasons:

{ "verified": true, "status": "approved", "reasons": [], "declined": false }

All of these parameters are secret key only: send them from your server. See the full list on POST /v3/initialize.

Integrating

Server API

Browser SDK

Reference

Link your own record with `external_id`

Bind an identity with `phone` / `email`

Reading it back

​Link your own record with external_id

​Bind an identity with phone / email

​Reading it back

Link your own record with `external_id`

Bind an identity with `phone` / `email`

Reading it back