Account linking

By default a person you verify is a guest, recognized only by the device ID in their browser. Account linking ties the verification to your own user record and, optionally, binds an identity that makes the person a member: a durable 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 user with `external_id`

Pass external_id to associate the session with a record on your side. It comes straight back when you confirm, so you can match the verified human to your user without a lookup table.

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 user
  }),
});
const { url } = await res.json();
// redirect the user to `url`; on confirm you'll get external_id back

Bind an identity with `phone` / `email`

Pass a phone or email to bind the person to a verified identifier. This is what makes them a member: 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"
}

Binding fails if that phone or email is already claimed by another person: an identity is one human. Handle the 400 by routing the user to sign in and re-assert their existing claim rather than creating a duplicate.

Reading it back

The linked external_id is returned on the confirmation, so the result is self-describing:

{
  "verified": true,
  "external_id": "user_123",
  "verification": { "external_id": "signup-flow", "external_tenant_id": null }
}

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

Verification processes

SDK and API

Advanced usage

Reference

Link your own user with `external_id`

Bind an identity with `phone` / `email`

Reading it back

​Link your own user with external_id

​Bind an identity with phone / email

​Reading it back

Link your own user with `external_id`

Bind an identity with `phone` / `email`

Reading it back