> ## Documentation Index
> Fetch the complete documentation index at: https://docs.verifyyou.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Account linking

> Tie a verification to your own user, and bind an identity that claims their uniqueness.

By default a person you verify is a [guest](/v3/concepts/members-vs-guests), 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](/v3/concepts/members-vs-guests): a durable claim to their own face record, portable across devices and browsers.

You link at [`POST /v3/initialize`](/v3/api/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](/v3/api/confirmations), so you can match the verified human to your user without a lookup table.

```ts theme={null}
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.

```json theme={null}
{
  "external_id": "user_123",
  "phone": "+12105550142"
}
```

<Warning>
  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.
</Warning>

## Reading it back

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

```json theme={null}
{
  "verified": true,
  "external_id": "user_123",
  "verification": { "external_id": "signup-flow", "external_tenant_id": null }
}
```

<Note>
  All of these parameters are **secret key only**: send them from your server.
  See the full list on [`POST /v3/initialize`](/v3/api/initialize).
</Note>