# Exporting users
Source: https://docs.verifyyou.com/docs/activity/exporting-the-list

Getting your results out as a CSV.

**Export** sits on a verification's own Activity tab, and offers **Copy** or **Download**. Filter first: you export what you filtered, which is the whole point of exporting rather than reading.

## Export users to take action after the fact

If you set **On collision** to *Allow + flag* instead of *Block*, acting on a result means acting in your own product, so the export is the handover: suspend the accounts, hold the payouts, or reconcile against your own records.

## Making it reconcile

Export gives you a row per person. To join those rows to your own users, give us a key going in.

On the code path, attach your own `external_id` when you start the session. On the no-code import, put your columns in the CSV and we keep them on the row: the product's own example is `name,email,last_seen_ip`, so the IP you have on file comes back beside the one we saw.

Without either, you are matching on whatever email or phone they gave the check, which holds until somebody used a different address with you than with us. Import what you will want to compare, because you cannot add it afterwards.

**Next:** [Reading Insights](/docs/insights/reading-insights)


# Comprehensive trust score
Source: https://docs.verifyyou.com/docs/activity/guest-profiles

How we use active and passive signals to protect your platform.

Clicking a row in Activity opens the person behind it.

We collect two kinds of signal on every check. Active ones come from the person in front of the camera: whether the face is live, how confident we were, whether we have seen it before. Passive ones come from everything around them: the IP and where it resolves to, the device and browser, how often they have appeared and how fast. Combined, they make a trust score, and because it is recalculated on every run it moves as the person's behaviour moves rather than sitting still from the day they signed up.

<Frame>
  <img alt="Trust snapshot panel showing score, claims, attributes and activity" />
</Frame>

## The score

A score out of 100 sits beside every tab. Everyone starts at 100, and anything suspicious we detect during the run subtracts from it, weighted by how suspicious it is.

The score shown is from this person's most recent scored pass, so it tells you about that run rather than standing as a permanent rating. Somebody who was clean last month and arrived through a datacenter IP this morning shows you this morning.

Read it as a priority. A high score means we found little worth reporting. As it falls, there is more to look at, and by the time it is in the low tens there is usually a clear reason sitting one click away. What it never does is decide anything: your configuration settles the pass or fail.

## What we saw: the Signals tab

The score is the summary. **Signals** is the evidence, grouped into five categories with a count against each and a filter for high, medium or low strength.

<Frame>
  <img alt="Signals tab grouped into five categories" />
</Frame>

**Capture** is the check itself: how many liveness attempts they made, how confident we were in the live face, and the reason if it failed. Several attempts and low confidence is the pattern behind most held-up screens and replays.

**Person** is what we estimated from the scan: an age range and a gender, each with its own confidence. Estimates rather than proof, and useful mainly when they contradict what the person told you.

**Location** is derived from the IP address: country, region and city. Worth holding against where you expected them, and against where they were last time.

**Device** is the platform, device type and browser. One person across several devices is normal. Several people on one device is not.

**Network** is usually the group that moves the score, and it is the hardest for somebody to hide. Whether the IP is a VPN, a datacenter, a Tor exit or already known for abuse, and whether the connection behaves like the browser it claims to be, which covers TLS automation, a TLS and user agent mismatch, and the TLS client itself. A person can change their face's surroundings far more easily than they can change how their traffic looks.

## What we flagged: the Flags tab

Anything our checks raised on this person, with the reason attached. Empty means every run came through clean rather than nothing being looked at.

## Where they have been: the History tab

Every confirmation this person appears in, newest first, including runs where they are only the evidence. A denial shows its reason inline, so `limit reached` tells you your own limit fired.

This is the tab that gives you a baseline. One low-scoring run from a first-timer is thin. One low-scoring run from somebody with twelve clean ones behind them is a change, and changes are what you want to catch.

## Who they are to you: the summary panel

**Claims** is the field to read first. It names the phone or email bound to this person, when it was proven and how. If there is one, this person can be recognised on any device, anywhere you run a check. If there is not, recognition stops at the device they used, and they will look new the next time they arrive on another one.

**Attributes** repeats the estimates from the scan alongside how many verifications they have with you in total.

**Activity** is their span with you: when they first and last verified, and how many devices we have seen them on.

**Next:** [Exporting users](/docs/activity/exporting-the-list)


# Reading Activity
Source: https://docs.verifyyou.com/docs/activity/reading-activity

The record of everyone who completed a check.

**Activity** is the record of everyone who completed a verification, most recent first.

[**Workspace Activity**](https://platform.verifyyou.com/dashboard/activity) covers every check you run. A row gives you the identifier they gave, or *No identifier given*, the time, a trust band, a trust score out of 100, the result, and a `TEST` badge if it came from test keys. The row menu opens that person's profile.

**A verification's own Activity tab** adds the working controls: **Needs action**, **Export**, row selection, rows per page, and sending the check by email. Go here when you are working a list. Go to workspace Activity when you are looking somebody up.

Email invites have their own funnel. On a verification running **Existing users**, the **Email invites** view tracks each invite through sent, opened, clicked and verified, so you can see who opened an invite and stopped, and who never opened it at all. Somebody who opens it and never finishes is telling you something different from somebody who never opened it. [Existing users setup](/docs/guides/existing-users) covers the sending itself.

<Frame>
  <img alt="A verification's Activity tab, with the Filter and Export controls highlighted above the list of people" />
</Frame>

## Looking up individual users

Search by email or phone.

The support case: somebody says they cannot get in. The row tells you what actually happened, because a denial carries its reason. `limit reached` means your own verification limit fired and they have already passed once. A liveness failure means the camera never confirmed a live person, and trying again in better light might work. Two different answers to give them.

The investigation case: you have seen something odd on your own platform from one account and you want to know what we saw. Search the identifier, open the person, and hold what we have against what you have, the location, the devices, and the history of every run they appear in.

## Filtering users

The **Filter** opens 26 fields, and they fall into four groups worth knowing.

**Where they came from**: Country, Region, City, Platform, Device type, Browser. Reach for these when you have a picture of where your real people are. If your panel is US-based and a cluster of sessions arrives from one city you have never recruited in, that is worth pulling out on its own, even before anything is flagged.

**How they arrived**: VPN, Datacenter IP, Tor exit, Known abuser IP, TLS automation, TLS / UA mismatch, TLS client. Augie at Snorkel uses these to catch people who pass the check and still cannot hide their infrastructure: a cluster of accounts on datacenter IPs, when real people are working from laptops at home.

**What the check saw**: Threat level, Face collision, Face collisions, Liveness denied, Liveness failure reason, Liveness attempts, Liveness confidence, Age low, Age high, Gender confidence. **Face collisions** is the one to start from on any audit. A collision is the same human passing a check twice, and [Configuration](/docs/verifications/configuration) decides what happens when one is found.

**Housekeeping**: Environment separates test traffic from live, and **Conflicts with** pulls up the records that clash with a given one.

**Next:** [Comprehensive trust score](/docs/activity/guest-profiles)


# Start guide
Source: https://docs.verifyyou.com/docs/get-started/getting-access

How you get a workspace, and the four things to do in it.

Our team creates your workspace and configures your first check with you.

<Steps>
  <Step title="Talk to us">
    [Book a demo](https://sales.verifyyou.com). We work with you to understand your use case and get you set up to start seeing value immediately.
  </Step>

  <Step title="We create your workspace">
    We set it up around whatever you are gating, configure your first check, and email you an invite.
  </Step>

  <Step title="You invite your team">
    From the **Team** page, once you are in. See [Team and roles](/docs/workspace/team-and-roles).
  </Step>
</Steps>

Four things to do [once you are in](https://platform.verifyyou.com/dashboard).

## Try a HumanCheck

Open the verification, go to **Integration**, and use **Run a test**. It runs the real check on test data with a test identity, so nothing touches your live records. Fail it on purpose too, so you have seen what your users see when it goes wrong.

## Understanding your use case

Configuration allows you to adjust how the check behaves to match your use case.

**What are you protecting?** Different use cases have different requirements, which we make simple to accommodate: A signup that allows one account per human refuses the second face outright. A userbase healthcheck runs over people who already have accounts, lets them all through, and tells you what it saw about each one. [Configuration](/docs/verifications/configuration) goes deeper on the concept and on which settings suit which job.

Pick the preset that matches the job: **Signup Gate**, **Account Sweep**, **AI Data Labeling Fraud Audit** or **Build Your Own**.

A preset is a sensible starting point for a general version of that job, not a finished setup. Two companies running signup gates often want different answers on how many times one person may pass, whether to ask for a phone or email, and what a duplicate should cost. Go through [Configuration](/docs/verifications/configuration) afterwards and make each setting match what you are actually protecting.

See how common use cases work: [Gate a signup](/docs/use-cases/signup-gate), [Gate key actions](/docs/use-cases/gate-key-actions), [Userbase healthcheck](/docs/use-cases/userbase-fraud-audit), [Persistent verification](/docs/use-cases/persistent-verification).

## Start protecting your platform

Choose how the check reaches people. No code gets you started with zero developer effort, so you can prove value early without interrupting your roadmap: share the verification's link, import your existing users and send each of them a request, or put one-time passwords in front of a survey. Code puts the check inside your own product with the SDK, with your server confirming the result. See [Integration](/docs/verifications/integration) for all four.

## Understanding your data

**Activity** lists everyone who completed the check, newest first, and opening a row gives you everything we saw about that person. **Flags** collects the people our checks caught, with the reason. **Insights** rolls all of it up across a period, so you can see the shape of your traffic rather than one person at a time.

See [Reading Activity](/docs/activity/reading-activity), [Flags](/docs/insights/flags) and [Reading Insights](/docs/insights/reading-insights).

**Next:** [Creating a verification](/docs/verifications/creating-a-verification)


# Glossary
Source: https://docs.verifyyou.com/docs/glossary

Every term this site uses, in plain language.

Every product picks up its own vocabulary, and the rest of these docs read more easily once the words are pinned down. Here are the terms HumanCheck uses, in plain language, grouped by where you will meet them. Each definition stands on its own, and the links point to the pages that go deeper.

<Note>
  These are the words the dashboard and the developer docs use, so what you read here lines up with what you will see on screen and in the API.
</Note>

## The product

### HumanCheck

The VerifyYou product: a short camera check that confirms a real, live, unique human, without ID documents. Companies place it in front of signups, surveys, and communities, anywhere that needs real people. [Guests and members](/docs/how-it-works/guests-and-members) has the full picture.

### Verification

A configured check in your dashboard. Each verification carries its own configuration, branding, and integration, and has its own link, insights, and activity, so you can run one for signups and another for a survey, each set up its own way. [Creating a verification](/docs/verifications/creating-a-verification) walks the wizard that makes one.

### Session

One run of a check by one person, from the moment it starts to a result or a walk-away. A session that reaches a decision is **settled**, and that is what Insights counts. [Guests and members](/docs/how-it-works/guests-and-members) follows one from start to finish.

### Redirect URL

Where a person lands after they finish the check. Set on the verification, in the **Where people land** panel, and in redirect mode it is also where the confirmation token arrives, so set it before you go live. The [quickstart](/v3/dev/integrating/start-a-session) shows where it fits.

## Members and guests

### Member

A person whose verified phone number or email is bound to their face record, which the developer docs call a **bound identity**. Ownership is proven with a one-time code during the flow, and that is what carries recognition across devices and browsers. [Guests and members](/docs/how-it-works/guests-and-members) goes deeper.

### Guest

A person recognized by their device ID and nothing else: no phone, no email, no name. The developer docs call this **anonymous**. Recognition stays with that device, so a guest on a new device or a cleared browser looks like somebody new. [Guests and members](/docs/how-it-works/guests-and-members) has the comparison.

### Device ID

The identifier that lets HumanCheck recognize a guest's device when it returns. A new device generally means a new device ID, which is why repeat visitors are better registered as members. [Guests and members](/docs/how-it-works/guests-and-members) covers the return moment.

### Skip check on known devices

The setting that lets somebody returning on a device you already know through without repeating the scan. Off by default, otherwise a window you choose. A person who skips the scan still counts as a verification. [Configuration](/docs/verifications/configuration) covers the options.

## What the check proves

### Liveness

The part of the check that confirms a real, present human is in front of the camera, not a photo, a replay, or a deepfake. [How it works](/docs/how-it-works/guests-and-members) walks through the whole flow.

### Uniqueness

The part of the check that confirms this human has not already passed under a different identity. New checks are compared against the face vectors already held, which is how a first-timer is told apart from someone coming back under a new name.

### Face vector

A numerical representation of the face's geometry, not a saved image. It is treated as sensitive biometric data, and verification images themselves are not stored. [Security and privacy](/docs/how-it-works/security-and-privacy) covers this honestly and in full.

## Matching and identity

### Collision

A new check whose face matches a face record that already exists, meaning the same person is trying to pass again where your rules say they should not. Depending on your configuration, a collision is blocked outright or flagged as suspicious.

### Access type

What the **Identity** panel calls its three options: *Linked by guest*, *Anonymous* and *Provided by you*. [Configuration](/docs/verifications/configuration) covers each.

### Group

A parameter your integration sends when it starts a session, so one verification can gate several separate things and somebody may pass once in each. It is not a control on the Configuration tab. See [start a session](/v3/dev/integrating/start-a-session).

### Preset

The starting point you pick in the wizard: **Signup Gate**, **Account Sweep**, **AI Data Labeling Fraud Audit** or **Build Your Own**. It sets the configuration, and you change what does not fit.

## Reading results

### Trust score

A number out of 100 on a person. Everyone starts at 100, and every signal we collect while they move through the flow takes points off. A high score means few signals came back on them. It never blocks anyone on its own: the pass or fail is settled by your configuration. See [Threat levels and signals](/docs/insights/threat-levels-and-signals).

### Threat band

How Insights groups scored sessions: **Low**, **Moderate**, **Elevated**, **High**. Higher means more concerning, which is the opposite direction to the trust score. The two describe one person from opposite ends.

### Threat families

What led the score across scored passes: network, geography, accounts, automation and liveness. Which family dominates tells you whether one person is repeating themselves or many people are arriving the same way. Not the same as the five signal groups on a person, which are Capture, Person, Location, Device and Network. See [Comprehensive trust score](/docs/activity/guest-profiles).

### Settled

A run that reached a decision. **Settled passes** on Insights counts them for the period you picked, alongside **liveness pass rate** and **elevated risk**.

### Needs action

A filter on a verification's Activity tab that narrows the list to the sessions the product has singled out. It is not on workspace Activity.

### Environment

The test and live split. Activity shows a `TEST` badge on test runs, and **Environment** is the filter that separates them.

### Decline

A graceful exit from the check. Turning on the decline banner adds an opt-out to the modal and returns a declined event to your product, so a person who would rather not verify has a way out and you find out they took it. See [Branding your check](/docs/verifications/branding-your-check).

## Keys, tokens, and testing

### Test keys and live keys

Your workspace has two secret keys, `sk_test_` for trying things out and `sk_live_` for production. Both stay on your server. Test and live are separate partitions and never mix, so a session minted with a test key confirms only with the test secret key. Publishable keys (`pk_`) are deprecated: start every session server side and open it in the browser. The [quickstart](/v3/dev/integrating/start-a-session) puts them to work.

### Simulator and test sessions

Test keys run against a simulator, so the code path works end to end without involving a real person. There are no-code test sessions too, so you can rehearse before anything goes live. The [quickstart](/v3/dev/integrating/start-a-session) uses them.

### external\_id

Your own identifier for the person being checked, passed when your server initializes a session with a secret key and echoed back on the confirmation. It lets you tie a result to your user without handing us their identity. [Account linking](/v3/advanced/account-linking) goes deeper.

### Confirmation token (vyt)

The token that travels back with a person after a check, as the vyt query parameter in redirect mode or through the onComplete callback in embedded modes. Your server exchanges it for the authoritative result. Confirm each token once, and lock it afterwards if the flow should be one shot. The [quickstart](/v3/dev/integrating/start-a-session) shows the exchange in code.

### vyc

A one-character hint that arrives next to the token: 1 suggests the check passed, 0 suggests it did not. It is only a hint for what to show on screen first. The token, confirmed from your server, is the truth. The [quickstart](/v3/dev/integrating/start-a-session) shows the two arriving together.

## Where to go next

<CardGroup>
  <Card title="Quickstart" icon="rocket" href="/v3/dev/integrating/start-a-session">
    Run your first verification end to end, with or without code.
  </Card>

  <Card title="Reading Activity" icon="chart-line" href="/docs/activity/reading-activity">
    Where these terms show up on screen, and how to read them.
  </Card>

  <Card title="Configure your check" icon="sliders" href="/docs/verifications/configuration">
    Set what the check asks for, how often one person may pass, and what happens on a duplicate.
  </Card>

  <Card title="Developer docs" icon="code" href="/v3/dev/integrating/start-a-session">
    Look up the SDK and the API.
  </Card>
</CardGroup>


# Alchemer setup
Source: https://docs.verifyyou.com/docs/guides/alchemer

Put HumanCheck in front of your Alchemer study. Five steps, no code.

<Steps>
  <Step title="Create your study">
    In Alchemer, exactly as you normally would, with one difference.

    1. Build your study as usual.
    2. Leave **page 1 empty**: your questions start on page 2. Page 1 is where the gate goes.

    <p><strong>You now have:</strong> a normal Alchemer study with an empty first page.</p>
  </Step>

  <Step title="Connect your study in VerifyYou">
    In your [VerifyYou dashboard](https://platform.verifyyou.com/dashboard/verifications), open a verification and go to the **Integration** tab.

    1. Make sure the method is **One-time passwords**. If it is set to something else, click **Switch method** and choose it.
    2. Under **Your survey platform**, pick **Alchemer**.
    3. Paste your **Alchemer survey link**, the share link from your study.
    4. Set **how many one-time passwords** you need, one per expected respondent. You can always generate more later.
    5. Click **Connect survey**. We generate your passwords and hand back your study link.

    <p><strong>You now have:</strong> your <strong>study link</strong> (share this one, not your Alchemer link) and your <strong>one-time passwords</strong>. Click **Copy list** to copy them for the next step.</p>

    <Frame>
      <img alt="VerifyYou Integration tab, connect a survey platform" />
    </Frame>

    <Frame>
      <img alt="VerifyYou study link ready with copy list" />
    </Frame>
  </Step>

  <Step title="Add your passwords to Alchemer">
    On **page 1** of your study.

    1. Click **Add New: Action** and pick **Login/Password**.
    2. Choose **"Individual (one-time) passwords that deactivate after use."**
    3. Paste your password list, one per line, and save. Keep this action alone on page 1.

    Alchemer's own [Login/Password action](https://help.alchemer.com/help/login-password-action) enforces the gate before your first question shows.

    <p><strong>You now have:</strong> a study that refuses anyone without a valid, unused password.</p>

    <Frame>
      <img alt="Alchemer one-time passwords editor" />
    </Frame>
  </Step>

  <Step title="Set the password to fill itself in">
    In the same Login/Password action.

    1. Open the **Display** tab.
    2. Set **Pre-populate Password** to the merge code `[url("vypw")]` and click **Save Action**.

    <p><strong>You now have:</strong> a gate that opens itself for verified respondents. The password lands in the box on its own.</p>

    <Frame>
      <img alt="Alchemer pre-populate password setting" />
    </Frame>
  </Step>

  <Step title="Share your VerifyYou link, not your Alchemer link">
    The link you hand out is the **study link from VerifyYou** (the `app.verifyyou.com/verification/...` one, from **Copy** in the dashboard), never your Alchemer link. This is the whole point: the VerifyYou link sends every respondent through the face check first, then redirects the verified ones into your Alchemer study with their one-time password already attached. Anyone who opens the raw Alchemer link skips the check, so only ever share the VerifyYou link, in your panel, your sample provider, or your invite email.

    <p><strong>You now have:</strong> a fielded study where everyone who reaches your questions came through the check. That's the whole setup.</p>
  </Step>
</Steps>

## What happens next

<div>
  <a href="/learn/what-your-users-see">
    <span>
      <Icon icon="mobile-screen" />
    </span>

    <span>
      <Icon icon="mobile-screen" />
    </span>

    <span>What your respondent sees</span>
    <span>See exactly what your respondent sees.</span>
  </a>

  <a href="/docs/guides/pre-generated-passwords">
    <span>
      <Icon icon="layer-group" />
    </span>

    <span>
      <Icon icon="layer-group" />
    </span>

    <span>The same mechanism, any platform</span>
    <span>Alchemer today. The same pattern works anywhere.</span>
  </a>
</div>


# Existing users setup
Source: https://docs.verifyyou.com/docs/guides/existing-users

Verify the people you already have, by email. Five steps, no code.

<Steps>
  <Step title="Create your verification">
    In your [VerifyYou dashboard](https://platform.verifyyou.com/dashboard/verifications), if you already have a verification you want to use, skip to step 2.

    1. Click **New verification** and pick your check. [Creating a verification](/docs/verifications/creating-a-verification) walks the wizard, and [Configuration](/docs/verifications/configuration) explains each setting.
    2. Choose **No code** when the wizard asks how the check will reach people.
    3. Add your logo and company name so the check carries your brand. [Branding your check](/docs/verifications/branding-your-check) shows what each part controls.
    4. Continue through to **Integration**.

    <p><strong>You now have:</strong> a live verification, branded as yours.</p>
  </Step>

  <Step title="Switch the method to Existing users">
    On the verification's **Integration** tab.

    1. Click **Switch method** and choose **Existing users**.
    2. Set where people land after they verify, under **Lands on**, with **Edit**. If you leave it unset, people see the default finish screen.

    <p><strong>You now have:</strong> the import view, ready to take your list.</p>

    <Frame>
      <img alt="Switch method dialog with Existing users selected" />
    </Frame>
  </Step>

  <Step title="Add your people">
    In the **Add people** panel on the same tab.

    1. Paste your list, or click **Upload CSV**. Whole spreadsheet rows are fine, with or without a header. The panel reads your list and tells you how many people are ready to add.
    2. Click **Add**, and **Map columns** opens before anything comes in. Four fields sit at the top: **Email address**, then **IP address**, **Impact figure** and **Date for the figure**, each marked optional. We match your columns to them automatically, and each match is a dropdown, so if we guessed wrong you point it at the right column yourself. Only email is required. Leave the others unmapped and the import still runs.
    3. Everything else in your file sits under **Extra data**, saved to each person's record, with a type on each column: currency, date, number, text. Tick a column under **Select columns to leave out** to skip it this time. Import whatever you would want to compare later. An IP address you hold comes back beside the one we see when that person verifies.
    4. Check the count at the foot of the step, importing so many critical fields and so many extra columns, then click **Confirm mapping**. Rows with no email are skipped and counted, and empty cells stay empty rather than being filled in for you.

    Each person you add gets a verification link locked to their address. Adding people never sends anything, so you can build the list over several sittings and send once, when you are ready.

    <p><strong>You now have:</strong> your people imported, each with their own locked link and your extra columns on their record, and nothing sent.</p>
  </Step>

  <Step title="Link the address your invites leave from">
    Under **Recently added**, click **View all** to open the verification's **Activity** tab.

    1. Click the address shown in the header, next to **Send unsent**. The **Senders** panel opens.
    2. Add your address with **Add sender** and confirm it. When it reads **Confirmed. Ready to send**, you can send.
    3. To send from your own domain, publish the TXT and CNAME records shown under **Your own domain** with your DNS provider, then click **Re-check**. Each record flips to **Live** once it is seen. You can send before the records are live, and having them in place keeps your invites out of spam, so plan this in before a large batch.

    <p><strong>You now have:</strong> a confirmed From address your invites will leave from.</p>
  </Step>

  <Step title="Send, and watch the results come in">
    On the **Activity** tab, with your people listed.

    1. Select the people to invite, or use **Send unsent** to reach everyone you have not contacted yet.
    2. Click **Send**. The dialog shows who is getting it and the address it leaves from.
    3. Pick the message under **Message**: **Initial invite** for a first ask, or the re-verification message for people you are inviting back. **Edit** opens the copy so you can make it yours.
    4. Confirm the send.

    We host the sending, so there is no mail system on your side to wire up. The **Email invites** view then tracks each invite through sent, opened, clicked and verified as people come through, so you can see who opened and stopped and who never opened at all, and [Reading Activity](/docs/activity/reading-activity) covers what to do with what arrives.

    <p><strong>You now have:</strong> invites out, and results arriving on Activity as each person verifies. That's the whole setup.</p>
  </Step>
</Steps>

<Note>
  **Beta note.** Existing users is in beta. Hosted sending also has a daily cap, and the counter on the Activity header shows where you stand against it today.
</Note>

## What happens next

<div>
  <a href="/docs/activity/reading-activity">
    <span>
      <Icon icon="list-check" />
    </span>

    <span>
      <Icon icon="list-check" />
    </span>

    <span>Reading Activity</span>
    <span>The record of everyone who completed a check.</span>
  </a>

  <a href="/docs/use-cases/userbase-fraud-audit">
    <span>
      <Icon icon="user-check" />
    </span>

    <span>
      <Icon icon="user-check" />
    </span>

    <span>Userbase healthcheck</span>
    <span>The use case this method was built for.</span>
  </a>
</div>


# Google Forms setup
Source: https://docs.verifyyou.com/docs/guides/google-forms

Put HumanCheck in front of your Google Form. Five steps, one script you never edit.

Google Forms cannot run a check before it shows a question. It has no hidden fields, no branching on a link parameter, and no way to ask an outside service anything while a respondent is looking at it. So HumanCheck holds the line in two places instead of one.

The check happens on our side, before anyone reaches your form. The clean-up happens in your own spreadsheet, the moment somebody submits. Together they mean only verified people reach your questions, and anything that slips past by going straight to your form URL is removed from your results within seconds.

<Note>
  Somebody who skipped the check can still open your form and press submit. What they cannot do is leave a trace in your data or get paid for it. If you need unverified people to be unable to load the page at all, [Qualtrics](/docs/guides/qualtrics) and [Alchemer](/docs/guides/alchemer) can do that and Google Forms cannot.
</Note>

<Steps>
  <Step title="Build your form">
    In Google Forms, exactly as you normally would, with two additions.

    1. Add a **Short answer** question called **Verification code**. Mark it **Required** and put it on the first page. Capitals and spacing do not matter.
    2. Underneath it, write something like "Filled in automatically, please leave this alone."
    3. Open the **Responses** tab and click the Sheets icon to send your responses to a Google Sheet. The rest of the setup lives in that sheet.
    4. In **Settings**, open **Responses** and turn **off** "Allow response editing." Without this, somebody could submit and then edit a valid code in afterwards.

    <p><strong>You now have:</strong> a normal Google Form with a code box on page one, and a spreadsheet collecting the answers.</p>
  </Step>

  <Step title="Connect your study in VerifyYou">
    In your [VerifyYou dashboard](https://platform.verifyyou.com/dashboard/verifications), open a verification and go to the **Integration** tab.

    1. Make sure the method is **One-time passwords**. If it is set to something else, click **Switch method** and choose it.
    2. Set **how many one-time passwords** you need. Ask for at least twenty percent more than the respondents you expect. Passwords cost nothing, and running out mid-study screens out real people.
    3. Click **Copy list** to copy your passwords. You need them in step four.

    <p><strong>You now have:</strong> your <strong>study link</strong>, which is the one you share, and your <strong>one-time passwords</strong>.</p>
  </Step>

  <Step title="Add the script to your spreadsheet">
    Open the Google Sheet your responses go to, not the form.

    1. Open **Extensions**, then **Apps Script**.
    2. Delete anything already in the editor and paste in the script from the bottom of this page.
    3. Click **Save**.
    4. Click **Deploy**, then **New deployment**. Click the gear beside "Select type" and choose **Web app**.
    5. Set **Execute as: Me** and **Who has access: Anyone**, then click **Deploy** and approve the permissions.
    6. In the function dropdown choose **`setUp`** and click **Run**.

    When Google warns that it has not verified this app, click **Advanced**, then **Go to (your project)**, then **Allow**. That message appears because this is a private script you own and have not published to anyone else.

    Your spreadsheet now has a tab called **VerifyYou codes**. Cell **G5** holds your **access link**, which you need in step five.

    <p><strong>You now have:</strong> a spreadsheet that checks every submission, and an access link that fills the code box on its own.</p>
  </Step>

  <Step title="Paste in your passwords">
    On the **VerifyYou codes** tab.

    1. Paste your passwords into **column A**, starting at A2.
    2. Type `Unused` beside each one in **column B**.

    That tab is your ledger. Status moves from Unused, to Issued when we hand somebody that password, to Used when they actually submit. It is also how you check the gate is running: if people are completing your survey and nothing is moving to Used, something is wrong.

    Keep this spreadsheet private. Anyone who can read your passwords can use them.

    <p><strong>You now have:</strong> a study that accepts a response only when it arrives with a valid, unused password.</p>
  </Step>

  <Step title="Share your VerifyYou link, not your form link">
    Two links to keep straight. In VerifyYou, set the destination for verified people to the **access link from cell G5**. Then the link you hand out to respondents is the **study link from VerifyYou**, never your Google Form link.

    Anyone who opens the raw form link skips the check, so only ever share the VerifyYou link, in your panel, your sample provider, or your invite email.

    <p><strong>You now have:</strong> a fielded study where everyone who reaches your questions came through the check. That's the whole setup.</p>
  </Step>
</Steps>

<Note>
  Your respondent goes straight from the check into your survey with nothing to click. The survey runs inside the access link's own page, so the address bar keeps saying `script.google.com` while they answer. Underneath the form there is a small "Survey not loading? Open it in a new page" line, for the rare case where a form will not display nested.
</Note>

## Test it before you field

The script starts in a safe mode where nothing is deleted. It writes what it would have done into a column called **VerifyYou status** in your responses sheet. Stay in that mode until all six behave.

<AccordionGroup>
  <Accordion title="A verified respondent">
    Open your access link with `?vyt=test123` on the end. You should go straight into your survey with the code already filled in, without clicking anything. One password should now say Issued. Submit, and the status column should say `verified` while that password flips to Used.
  </Accordion>

  <Accordion title="The same person coming back">
    Open the exact same link again. You should get the **same** password back, not a new one. This is what stops somebody who abandons your survey and returns from consuming two.
  </Accordion>

  <Accordion title="Somebody who skipped the check">
    Open your plain form URL, leave the code box empty, and submit. The status should say `REJECTED: no code`.
  </Accordion>

  <Accordion title="A made-up code">
    Type any invented string into the code box and submit. The status should say `REJECTED: code not in pool`.
  </Accordion>

  <Accordion title="A password used twice">
    Submit once from a prefilled link, then open that same link again and submit a second time. The first should say `verified`. The second should say `REJECTED: code already used`. This is the check that proves one password cannot buy two responses, which is the whole reason the pool exists.
  </Accordion>

  <Accordion title="A broken setup">
    Rename the VerifyYou codes tab, submit anything, then rename it back. The status should say `unchecked`, and never `verified`. This one matters most: it proves that if your setup breaks, it tells you rather than quietly waving everybody through.
  </Accordion>
</AccordionGroup>

When all six behave, change `onInvalid` near the top of the script from `'FLAG'` to `'DELETE'` and click **Save**. That takes effect straight away, because the check that runs on each submission always uses your latest saved code.

Deploying is a separate thing, and it is the step people lose an hour to. Anything that changes how your **access link** behaves goes live only when you click **Deploy**, then **Manage deployments**, then the pencil icon, then set **Version** to **New version**, then **Deploy**. Save the file without doing that and you will still be served the old version, and conclude the change did not work.

## When something looks wrong

<AccordionGroup>
  <Accordion title="Responses arrive with a blank status column">
    The script is not running. Run `setUp` again from the script editor.
  </Accordion>

  <Accordion title="Everything says unchecked">
    Your codes tab is named something other than `VerifyYou codes`, or it is empty. Check the tab name matches exactly.
  </Accordion>

  <Accordion title="Everything is rejected, including your own test">
    The passwords in your sheet are not the ones being handed out. Copy your list again and paste it in fresh.
  </Accordion>

  <Accordion title="Nothing changed after you edited the script">
    It depends what you changed. `onInvalid` takes effect the moment you save, because the submission check always runs your latest saved code. Anything that changes how your access link behaves needs a new deployed version: **Deploy**, **Manage deployments**, the pencil icon, then **Version: New version**.
  </Accordion>

  <Accordion title="Respondents see a blank page with a Survey not loading line">
    Your form is not displaying nested inside the access link. They can click that line to carry on, and you should tell us, because it means we should move you to the button version instead.
  </Accordion>

  <Accordion title="This link needs to be opened through your study link">
    The access link was opened without a token on the end. That is expected if you opened it directly rather than through your VerifyYou study link. If real respondents see it, the token is not reaching the script, which is a VerifyYou setting rather than a problem with your form.
  </Accordion>

  <Accordion title="Anyone is greyed out when deploying">
    Your organisation's Google administrator has switched off public web apps. You will need their help, or an account without that restriction.
  </Accordion>

  <Accordion title="How many passwords are left">
    Run `vyPoolStatus` in the script editor any time. It reports how many are unused, how many we issued that nobody submitted, and how many people spent.
  </Accordion>
</AccordionGroup>

## Your data stays yours

Your passwords and your responses live in your Google account. What we hold is a list of verification sessions with no survey answers attached to any of them. There is no point at which we have both halves, so we could not connect a person to their answers even if we were asked to. If your ethics board asks how the two are kept apart, that is the answer, and you are welcome to point them at this page.

The script makes no connections outside your Google account.

## The script

Paste this whole thing into **Extensions**, then **Apps Script**, on your responses spreadsheet. The only line you ever change is `onInvalid`, and only when you finish testing.

<Accordion title="Show the script">
  ```javascript HumanCheck backstop wrap theme={null}
  /**
   * VerifyYou HumanCheck backstop for Google Forms
   * Version 1.0
   *
   * WHAT THIS DOES
   * Every time someone submits your form, this checks the verification code they
   * arrived with against your pool of issued codes. Valid and unused means the
   * response is kept and the code is marked used. Missing, unknown, or already
   * used means the response is removed, from both your spreadsheet and the form.
   *
   * It makes no external network calls. Everything happens inside your own Google
   * account, so nobody outside it sees your codes or your response data.
   *
   * SETUP
   * Run setUp() once from this editor and approve the permissions prompt.
   *
   * This script is bound to the RESPONSE SPREADSHEET, not the form. That is
   * deliberate: the spreadsheet's form-submit trigger hands us the exact row that
   * was just written, so there is no guessing and no race with the row appearing.
   */

  const VY = {
    // Tab holding your codes.
    //   A: Code   B: Status (Unused/Issued/Used)   C: Issued at   D: Used at   E: Token
    //   G2: link template          G5: dispenser URL (once deployed)
    poolTabName: 'VerifyYou codes',

    // Exact title of the short answer question that receives the code.
    codeQuestionTitle: 'Verification code',

    // Optional. If you add a short answer question with this title, the participant
    // ID from your recruitment platform is carried into it too. Leave the question
    // out of your form if you do not need it.
    participantQuestionTitle: 'Participant ID',

    // 'DELETE' removes bad responses.
    // 'FLAG' keeps everything and writes a status column instead. Use FLAG while
    // you are testing so you can see what would have happened before it is final.
    onInvalid: 'FLAG',

    // Header written into the response sheet when onInvalid is 'FLAG'.
    statusColumnHeader: 'VerifyYou status',

    // How the dispenser hands the respondent over to the form.
    //
    // A silent redirect of the whole browser tab is NOT possible here, and that is
    // a Google restriction rather than something fixable in this file. Apps Script
    // serves web apps inside a restricted iframe that is not granted
    // allow-top-navigation, and grants allow-top-navigation-by-user-activation
    // only to stand-alone script projects, not container-bound ones like this.
    // Google's own documented advice is to use a link or button instead.
    //
    //   'BUTTON' = one clean "Start the survey" button. Honest and obvious, but it
    //              is a click, on a script.google.com page, right after you asked
    //              someone for a face scan.
    //   'EMBED'  = no click. Loads the form inside the page instead of navigating
    //              away, which sidesteps top navigation entirely. The address bar
    //              keeps saying script.google.com and the form runs nested.
    dispenserMode: 'EMBED',
  };

  // ---------------------------------------------------------------------------
  // SETUP
  // ---------------------------------------------------------------------------

  /**
   * Run this once. Creates the code pool tab if it is missing and installs the
   * form-submit trigger. Safe to run again; it will not create duplicate triggers.
   */
  function setUp() {
    const ss = SpreadsheetApp.getActiveSpreadsheet();

    // doGet runs outside the spreadsheet's context, where "active spreadsheet" is
    // not reliably defined. Stash the ID now and open by ID later.
    PropertiesService.getScriptProperties().setProperty('VY_SS_ID', ss.getId());

    let pool = ss.getSheetByName(VY.poolTabName);
    if (!pool) pool = ss.insertSheet(VY.poolTabName);
    pool.getRange('A1:E1').setValues([['Code', 'Status', 'Issued at', 'Used at', 'Token']]);
    pool.setFrozenRows(1);

    // Remove any trigger we installed previously, so re-running is safe.
    ScriptApp.getProjectTriggers()
      .filter(function (t) { return t.getHandlerFunction() === 'vyOnFormSubmit'; })
      .forEach(function (t) { ScriptApp.deleteTrigger(t); });

    ScriptApp.newTrigger('vyOnFormSubmit')
      .forSpreadsheet(ss)
      .onFormSubmit()
      .create();

    const template = vyWritePrefillTemplate_(ss, pool);

    const codes = vyCountCodes_(pool);
    const message =
      'VerifyYou backstop installed.\n\n' +
      'Codes: ' + codes.total + ' total, ' + codes.unused + ' unused, ' +
        codes.issued + ' issued, ' + codes.used + ' used\n' +
      'Dispenser: ' + (vyDispenserUrl_() || 'not deployed (optional, see runbook)') + '\n' +
      'Mode: ' + VY.onInvalid + '\n' +
      'Link template: ' + (template ? 'ready' : 'PROBLEM, reason is in G2') +
        ' (cell G2 of the "' + VY.poolTabName + '" tab)\n\n' +
      (codes.total === 0
        ? 'Next step: paste your codes into column A of the "' + VY.poolTabName + '" tab.'
        : 'You are ready to test.');
    Logger.log(message);
    if (template) Logger.log(template);
    try { ss.toast(message, 'VerifyYou', 15); } catch (err) { /* toast is best effort */ }
  }

  /**
   * Asks Google to generate the pre-fill link for us, rather than anyone building
   * it by hand.
   *
   * Hand-assembling this URL has three silent failure modes: appending &entry to a
   * URL with no query string, using the editor URL instead of the public one, and
   * using a forms.gle short link, which drops the query string on redirect. Each
   * one loads the form normally with an empty code field, so it fails invisibly.
   * toPrefilledUrl() sidesteps all of them because Google emits the URL itself:
   * correct public ID, correct entry IDs, correct encoding.
   *
   * The response is created but never submitted, so nothing lands in your results.
   */
  function vyGetPrefillTemplate() {
    const ss = SpreadsheetApp.getActiveSpreadsheet();
    const pool = ss.getSheetByName(VY.poolTabName);
    const url = vyWritePrefillTemplate_(ss, pool);
    if (url) Logger.log(url);
    return url;
  }

  /**
   * Titles are compared trimmed and lower-cased everywhere. "Verification Code"
   * and "Verification code" are the same question as far as this script is
   * concerned. Exact matching looks tidy and is a trap: Google Forms gives no hint
   * that capitals matter, so the natural way to type a title silently breaks
   * everything downstream.
   */
  function vyNorm_(s) {
    return String(s || '').trim().toLowerCase();
  }

  function vyWritePrefillTemplate_(ss, pool) {
    const formUrl = ss.getFormUrl();
    if (!formUrl) {
      return vyTemplateProblem_(pool,
        'This spreadsheet is not linked to a form. Open the form, go to the Responses tab, and link it here.');
    }

    const form = FormApp.openByUrl(formUrl);
    let response = form.createResponse();
    let found = false;
    const seen = [];

    form.getItems().forEach(function (item) {
      const type = item.getType();
      const isText = type === FormApp.ItemType.TEXT;
      const isPara = type === FormApp.ItemType.PARAGRAPH_TEXT;
      if (!isText && !isPara) return;

      const title = item.getTitle();
      seen.push(title);

      const answer = function (value) {
        return isText
          ? item.asTextItem().createResponse(value)
          : item.asParagraphTextItem().createResponse(value);
      };

      // The code question, and optionally a participant ID question, get
      // placeholders our gate substitutes at redirect time.
      if (vyNorm_(title) === vyNorm_(VY.codeQuestionTitle)) {
        response = response.withItemResponse(answer('__VY_CODE__'));
        found = true;
      } else if (vyNorm_(title) === vyNorm_(VY.participantQuestionTitle)) {
        response = response.withItemResponse(answer('__VY_PID__'));
      }
    });

    if (!found) {
      return vyTemplateProblem_(pool,
        'No question matching "' + VY.codeQuestionTitle + '" was found. ' +
        'Text questions in your form: ' + (seen.length ? seen.join('  |  ') : 'none') + '. ' +
        'Either rename one of them, or change codeQuestionTitle at the top of this script.');
    }

    const url = response.toPrefilledUrl();

    if (pool) {
      pool.getRange('G1').setValue('Link template');
      pool.getRange('G2').setValue(url);
      pool.getRange('G4').setValue('Access link (paste THIS into VerifyYou)');
      pool.getRange('G5').setValue(vyDispenserUrl_() || 'not deployed yet, see step 6 of the runbook');
      pool.setColumnWidth(7, 460);
    }
    return url;
  }

  /**
   * Writes the reason into G2 rather than leaving it blank. A blank cell tells you
   * nothing; the reason tells you everything, and it appears where you are already
   * looking instead of in an execution log you would have to go and open.
   */
  function vyTemplateProblem_(pool, message) {
    Logger.log(message);
    if (pool) {
      pool.getRange('G1').setValue('Link template (PROBLEM)');
      pool.getRange('G2').setValue(message);
      pool.setColumnWidth(7, 460);
    }
    return '';
  }

  /** The deployed web app URL, or '' if this has not been deployed yet. */
  function vyDispenserUrl_() {
    try {
      return ScriptApp.getService().getUrl() || '';
    } catch (err) {
      return '';
    }
  }

  // ---------------------------------------------------------------------------
  // THE DISPENSER (web app)
  // ---------------------------------------------------------------------------
  //
  // TEST HARNESS, not the shipping design. Read this before relying on it.
  //
  // Deploy → New deployment → Web app, "Execute as: Me", "Who has access: Anyone".
  // Google hosts it. Paste the resulting URL into VerifyYou as the verified
  // destination, INSTEAD of your form URL.
  //
  // Three things to know:
  //   1. It cannot verify the token. Confirming a token server-side needs the
  //      VerifyYou SECRET key, which must never sit in a researcher's script. So
  //      this checks that a token is present and refuses to issue twice for the
  //      same one. That stops sharing and refreshes. It does not stop somebody
  //      deliberately sending made-up tokens to drain the pool.
  //   2. It fails CLOSED. If this breaks, hits a quota, or loses authorization,
  //      verified people get no code and cannot enter the study at all. The
  //      submit-side check fails open; this one is the opposite, and it sits on
  //      the critical path of live fielding.
  //   3. "Anyone, even anonymous" can be disabled by a Workspace administrator,
  //      and on some account types it is not offered. If you cannot select it,
  //      this approach is not available on that account.

  function doGet(e) {
    const params = (e && e.parameter) || {};

    // Two ways a password can arrive.
    //
    // PASSTHROUGH (preferred): VerifyYou already issues a one-time password per
    // verified human and drops it on the link, which is how the Alchemer setup
    // works, where it lands as ?vypw=. Nothing left to decide, so just carry it
    // into the form. VerifyYou owns issuance, reissue on abandonment, and running
    // out, which is exactly where that belongs.
    //
    // CLAIM (fallback): only a ?vyt= token arrives, so this script picks the next
    // unused password out of the sheet itself.
    const supplied = String(params.vypw || params.vyp || '').trim();
    const token = String(params.vyt || params.vyc || '').trim();
    const pid = String(params.pid || params.PROLIFIC_PID || params.participant || '').trim();

    if (!supplied && !token) {
      return vyDispenserPage_('This link needs to be opened through your study link, not directly.');
    }

    const lock = LockService.getScriptLock();
    try {
      lock.waitLock(30000);
    } catch (err) {
      return vyDispenserPage_('Busy right now. Please refresh in a few seconds.');
    }

    try {
      const ssId = PropertiesService.getScriptProperties().getProperty('VY_SS_ID');
      if (!ssId) return vyDispenserPage_('Not set up yet. Run setUp from the script editor.');

      const ss = SpreadsheetApp.openById(ssId);
      const pool = ss.getSheetByName(VY.poolTabName);
      if (!pool) return vyDispenserPage_('No codes tab found. Run setUp from the script editor.');

      const template = String(pool.getRange('G2').getValue() || '');
      if (template.indexOf('__VY_CODE__') === -1) {
        return vyDispenserPage_('No link template. Run setUp from the script editor.');
      }

      // Passthrough beats claiming. If VerifyYou already picked the password, use
      // it and note it against the pool row so the sheet still shows what happened.
      let code = supplied;
      if (code) {
        vyMarkIssued_(pool, code, token);
      } else {
        code = vyClaimCode_(pool, token);
      }

      if (!code) {
        // Pool exhausted. Verified people arriving with nothing is the worst
        // failure this design has, because in the results they look like bots.
        return vyDispenserPage_(
          'This study has run out of access codes. Please contact the researcher; ' +
          'you have not done anything wrong.');
      }

      let url = template.split('__VY_CODE__').join(encodeURIComponent(code));
      url = url.split('__VY_PID__').join(encodeURIComponent(pid));
      return vyRedirect_(url, String(params.debug || '') === '1');
    } catch (err) {
      Logger.log('VerifyYou dispenser error: ' + err);
      return vyDispenserPage_('Something went wrong opening the survey. Please contact the researcher.');
    } finally {
      lock.releaseLock();
    }
  }

  /**
   * Claims a code for this token. Idempotent by token: the same person refreshing,
   * or coming back after abandoning, gets the SAME code rather than spending
   * another one. Returns '' when the pool is exhausted.
   */
  function vyClaimCode_(pool, token) {
    const last = vyLastCodeRow_(pool);
    if (last < 2) return '';

    const rows = pool.getRange(2, 1, last - 1, 5).getValues();

    // Already issued to this token? Hand back the same code.
    for (let i = 0; i < rows.length; i++) {
      if (String(rows[i][4] || '').trim() === token) return String(rows[i][0]).trim();
    }

    // Otherwise take the first Unused one.
    for (let i = 0; i < rows.length; i++) {
      const code = String(rows[i][0] || '').trim();
      if (!code) continue;
      if (String(rows[i][1] || '').trim().toLowerCase() !== 'unused') continue;

      pool.getRange(i + 2, 2, 1, 2).setValues([['Issued', new Date()]]);
      pool.getRange(i + 2, 5).setValue(token);
      SpreadsheetApp.flush();
      return code;
    }
    return '';
  }

  /**
   * Marks a password VerifyYou already chose as Issued, so the sheet reflects
   * reality. Deliberately quiet if the password is not in the pool: VerifyYou is
   * the authority on what it issued, and the submit-side check is what decides
   * whether a response is kept.
   */
  function vyMarkIssued_(pool, code, token) {
    const last = vyLastCodeRow_(pool);
    if (last < 2) return;
    const rows = pool.getRange(2, 1, last - 1, 2).getValues();
    for (let i = 0; i < rows.length; i++) {
      if (String(rows[i][0]).trim() !== code) continue;
      if (String(rows[i][1] || '').trim().toLowerCase() === 'unused') {
        pool.getRange(i + 2, 2, 1, 2).setValues([['Issued', new Date()]]);
        if (token) pool.getRange(i + 2, 5).setValue(token);
        SpreadsheetApp.flush();
      }
      return;
    }
  }

  /**
   * Hands the respondent over to the form. See VY.dispenserMode for why a silent
   * whole-tab redirect is not on the menu.
   */
  function vyRedirect_(url, debug) {
    const html = (VY.dispenserMode === 'EMBED' && !debug)
      ? vyEmbedHtml_(url)
      : vyButtonHtml_(url, debug);
    return HtmlService.createHtmlOutput(html)
      .setXFrameOptionsMode(HtmlService.XFrameOptionsMode.ALLOWALL)
      .setTitle('Your survey');
  }

  /**
   * One button. It still attempts the automatic hop first, which costs nothing and
   * covers the case where a browser or a future deployment type does permit it.
   * Anchors carrying target="_top" are user-initiated, which is the one form of
   * top navigation those restrictions do allow.
   */
  function vyButtonHtml_(url, debug) {
    const attr = String(url).replace(/&/g, '&amp;').replace(/"/g, '&quot;').replace(/</g, '&lt;');

    // Whether the automatic hop can work comes down to one thing: is this page
    // inside Google's restricted iframe or not. If window.self === window.top there
    // is nothing in the way and the redirect just works. Add ?debug=1 to the
    // dispenser URL to see which situation a given deployment is in.
    const probe = debug
      ? '<pre id="vydbg" style="text-align:left;background:#f6f8fa;padding:1rem;border-radius:8px;' +
        'margin-top:2rem;font-size:.8rem;white-space:pre-wrap"></pre>' +
        '<script>(function(){var f;try{f=(window.self!==window.top);}catch(e){f="cross-origin (so: framed)";}' +
        'document.getElementById("vydbg").textContent=' +
        '"framed: "+f+"\\nself origin: "+location.origin+"\\nua: "+navigator.userAgent;})();<\/script>'
      : '';

    return '<!DOCTYPE html><html><head><meta charset="utf-8"><title>Your survey</title></head>' +
      '<body style="font-family:system-ui,-apple-system,sans-serif;margin:0;padding:3rem 1.5rem;' +
      'text-align:center;color:#1f2328">' +
      '<p style="font-size:1.05rem;margin:0 0 .5rem">You are verified.</p>' +
      '<p style="color:#5b6470;margin:0 0 2rem">Continue to the survey below.</p>' +
      '<a href="' + attr + '" target="_top" ' +
      'style="display:inline-block;padding:.9rem 2rem;border-radius:8px;background:#34A853;' +
      'color:#fff;text-decoration:none;font-weight:600">Start the survey</a>' +
      probe +
      (debug ? '' :
        '<script>try{window.top.location.href=' + JSON.stringify(String(url)) + ';}catch(e){}<\/script>') +
      '</body></html>';
  }

  /**
   * No click. Navigates this frame rather than the top one, which those frame
   * restrictions do not cover, so the form loads in place. Forms supports being framed,
   * which is what its own embed feature relies on.
   */
  function vyEmbedHtml_(url) {
    const esc = function (s) {
      return String(s).replace(/&/g, '&amp;').replace(/"/g, '&quot;').replace(/</g, '&lt;');
    };
    const embed = String(url) + (String(url).indexOf('?') === -1 ? '?' : '&') + 'embedded=true';

    // The escape hatch matters more than it looks. If the form ever fails to render
    // in the frame, without this the respondent gets a blank page and no way
    // forward, which is worse than the button we were trying to avoid. It stays
    // small and out of the way until someone needs it.
    return '<!DOCTYPE html><html><head><meta charset="utf-8"><title>Your survey</title>' +
      '<style>html,body{margin:0;height:100%;font-family:system-ui,-apple-system,sans-serif}' +
      '#f{border:0;width:100%;height:calc(100% - 34px);display:block}' +
      '#b{height:34px;display:flex;align-items:center;justify-content:center;font-size:.78rem;color:#8a939f}' +
      '#b a{color:#8a939f}</style></head>' +
      '<body>' +
      '<iframe id="f" src="' + esc(embed) + '">Loading your survey…</iframe>' +
      '<div id="b">Survey not loading? <a href="' + esc(url) + '" target="_top">' +
      '&nbsp;Open it in a new page</a></div>' +
      '</body></html>';
  }

  function vyDispenserPage_(message) {
    const html =
      '<!DOCTYPE html><html><head><meta charset="utf-8"><title>Survey access</title></head>' +
      '<body style="font-family:system-ui,-apple-system,sans-serif;padding:2rem;text-align:center">' +
      '<p>' + String(message).replace(/</g, '&lt;') + '</p></body></html>';
    return HtmlService.createHtmlOutput(html)
      .setXFrameOptionsMode(HtmlService.XFrameOptionsMode.ALLOWALL)
      .setTitle('Survey access');
  }

  // ---------------------------------------------------------------------------
  // RUNTIME
  // ---------------------------------------------------------------------------

  function vyOnFormSubmit(e) {
    // Serialise every execution. Google guarantees a script lock cannot be held
    // by two executions at once regardless of who triggered them, which is what
    // stops two submissions redeeming the same code simultaneously.
    const lock = LockService.getScriptLock();
    try {
      lock.waitLock(30000);
    } catch (err) {
      // Could not get the lock. Fail open: never destroy a real response because
      // this script was busy.
      vyFlagRow_(e, 'unchecked (script busy)');
      return;
    }

    try {
      const ss = SpreadsheetApp.getActiveSpreadsheet();
      const code = vyExtractCode_(e);
      const verdict = vyRedeem_(ss, code);

      // Fail-open paths are labelled as such. They must never read as 'verified',
      // or a setup mistake looks like a clean study.
      if (verdict.failOpen) {
        vyFlagRow_(e, 'unchecked (' + verdict.reason + ')');
        return;
      }

      if (verdict.ok) {
        vyFlagRow_(e, 'verified');
        return;
      }

      if (VY.onInvalid === 'FLAG') {
        vyFlagRow_(e, 'REJECTED: ' + verdict.reason);
        return;
      }

      vyRemoveResponse_(ss, e, code);
    } catch (err) {
      // Any unexpected failure fails open, with a note, rather than deleting data.
      Logger.log('VerifyYou backstop error: ' + err);
      try { vyFlagRow_(e, 'unchecked (error)'); } catch (ignored) {}
    } finally {
      lock.releaseLock();
    }
  }

  /**
   * Reads the submitted code. namedValues is keyed by question title, matched
   * case-insensitively for the same reason as everywhere else.
   */
  function vyExtractCode_(e) {
    const named = e.namedValues || {};
    const wanted = vyNorm_(VY.codeQuestionTitle);
    const keys = Object.keys(named);
    for (let i = 0; i < keys.length; i++) {
      if (vyNorm_(keys[i]) !== wanted) continue;
      const raw = named[keys[i]];
      if (!raw || !raw.length) return '';
      return String(raw[0]).trim();
    }
    return '';
  }

  /**
   * Looks the code up in the pool and marks it used. Returns {ok, reason}.
   * Runs inside the script lock, so the read and the write are effectively atomic.
   */
  function vyRedeem_(ss, code) {
    if (!code) return { ok: false, reason: 'no code' };

    const pool = ss.getSheetByName(VY.poolTabName);
    if (!pool) return { ok: false, failOpen: true, reason: 'no pool tab' };

    // Measured on column A, not getLastRow(). The link template sits in G2, so a
    // sheet with a template but no codes would otherwise look non-empty and start
    // rejecting people instead of failing open.
    const last = vyLastCodeRow_(pool);
    if (last < 2) return { ok: false, failOpen: true, reason: 'pool empty' };

    const values = pool.getRange(2, 1, last - 1, 2).getValues();
    for (let i = 0; i < values.length; i++) {
      if (String(values[i][0]).trim() !== code) continue;

      // Unused (typed in by hand during testing) and Issued (handed out by the
      // dispenser) both redeem. Only Used is a genuine second attempt.
      const status = String(values[i][1] || '').trim().toLowerCase();
      if (status === 'used') return { ok: false, reason: 'code already used' };

      pool.getRange(i + 2, 2).setValue('Used');
      pool.getRange(i + 2, 4).setValue(new Date());
      SpreadsheetApp.flush();
      return { ok: true, reason: 'redeemed' };
    }

    return { ok: false, reason: 'code not in pool' };
  }

  /**
   * Deletes the response from the sheet and, best effort, from the form itself.
   */
  function vyRemoveResponse_(ss, e, code) {
    const sheet = e.range.getSheet();
    const rowValues = e.values || [];

    // Re-locate the row inside the lock rather than trusting the row index
    // captured before it. An earlier deletion may have shifted everything up.
    const row = vyFindRow_(sheet, rowValues);
    if (row > 1) sheet.deleteRow(row);

    vyDeleteFormResponse_(ss, rowValues, code);
  }

  /**
   * Finds the row matching this submission, searching newest first. Compares the
   * answer columns rather than the timestamp, since the sheet stores a Date and
   * the event gives a string.
   */
  function vyFindRow_(sheet, rowValues) {
    if (!rowValues.length) return -1;
    const data = sheet.getDataRange().getValues();
    for (let r = data.length - 1; r >= 1; r--) {
      let match = true;
      for (let c = 1; c < rowValues.length; c++) {
        if (String(data[r][c]) !== String(rowValues[c])) { match = false; break; }
      }
      if (match) return r + 1;
    }
    return -1;
  }

  /**
   * Removes the form's own copy so its response count and summary charts stay
   * honest. Matched on the code where we have one, on timestamp where we do not.
   */
  function vyDeleteFormResponse_(ss, rowValues, code) {
    const formUrl = ss.getFormUrl();
    if (!formUrl) return;

    const submitted = new Date(rowValues[0]);
    const since = new Date(submitted.getTime() - 120000);

    const form = FormApp.openByUrl(formUrl);
    const responses = form.getResponses(since);

    for (let i = 0; i < responses.length; i++) {
      const r = responses[i];
      let hit = false;

      if (code) {
        const items = r.getItemResponses();
        for (let j = 0; j < items.length; j++) {
          if (vyNorm_(items[j].getItem().getTitle()) === vyNorm_(VY.codeQuestionTitle) &&
              String(items[j].getResponse()).trim() === code) { hit = true; break; }
        }
      } else {
        hit = Math.abs(r.getTimestamp().getTime() - submitted.getTime()) < 2000;
      }

      if (hit) { form.deleteResponse(r.getId()); return; }
    }
  }

  /**
   * Writes a status next to the response. Used for 'verified', for FLAG mode, and
   * for every fail-open path so nothing is ever silently unchecked.
   */
  function vyFlagRow_(e, status) {
    const sheet = e.range.getSheet();
    const header = sheet.getRange(1, 1, 1, Math.max(sheet.getLastColumn(), 1)).getValues()[0];

    let col = header.indexOf(VY.statusColumnHeader) + 1;
    if (col === 0) {
      col = sheet.getLastColumn() + 1;
      sheet.getRange(1, col).setValue(VY.statusColumnHeader);
    }

    const row = vyFindRow_(sheet, e.values || []);
    if (row > 1) sheet.getRange(row, col).setValue(status);
  }

  /** Last row of column A holding a code. Ignores anything in other columns. */
  function vyLastCodeRow_(pool) {
    const values = pool.getRange(1, 1, Math.max(pool.getMaxRows(), 1), 1).getValues();
    for (let r = values.length - 1; r >= 0; r--) {
      if (String(values[r][0]).trim()) return r + 1;
    }
    return 0;
  }

  function vyCountCodes_(pool) {
    const last = vyLastCodeRow_(pool);
    if (last < 2) return { total: 0, unused: 0, issued: 0, used: 0 };
    const values = pool.getRange(2, 1, last - 1, 2).getValues();
    let total = 0, unused = 0, issued = 0, used = 0;
    values.forEach(function (v) {
      if (!String(v[0]).trim()) return;
      total++;
      const s = String(v[1] || '').trim().toLowerCase();
      if (s === 'used') used++;
      else if (s === 'issued') issued++;
      else unused++;
    });
    return { total: total, unused: unused, issued: issued, used: used };
  }

  // ---------------------------------------------------------------------------
  // HELPERS YOU CAN RUN BY HAND
  // ---------------------------------------------------------------------------

  /** Generates test codes into the pool tab. For trying this out before go live. */
  function vyGenerateTestCodes() {
    const ss = SpreadsheetApp.getActiveSpreadsheet();
    const pool = ss.getSheetByName(VY.poolTabName) || ss.insertSheet(VY.poolTabName);
    if (pool.getLastRow() === 0) {
      pool.getRange('A1:C1').setValues([['Code', 'Status', 'Used at']]);
    }
    const rows = [];
    for (let i = 0; i < 20; i++) rows.push([vyRandomCode_(), 'Unused', '', '', '']);
    // Append after the last CODE, not the last row, so the template block in
    // column G does not push new codes down and leave a gap.
    pool.getRange(Math.max(vyLastCodeRow_(pool), 1) + 1, 1, rows.length, 5).setValues(rows);
    Logger.log('Added ' + rows.length + ' test codes.');
  }

  /**
   * 22 characters from a 30 character alphabet, roughly 108 bits. Short or
   * sequential codes in a known pool are guessable by anyone who strips the
   * prefill and tries, which is the one way to get this design wrong.
   */
  function vyRandomCode_() {
    const alphabet = 'ABCDEFGHJKMNPQRSTVWXYZ23456789';
    let hex = '';
    while (hex.length < 44) hex += Utilities.getUuid().replace(/-/g, '');
    let out = 'vy-';
    for (let i = 0; i < 22; i++) {
      out += alphabet.charAt(parseInt(hex.substr(i * 2, 2), 16) % alphabet.length);
    }
    return out;
  }

  /**
   * For running the dispenser as a STANDALONE script project instead of one bound
   * to the spreadsheet. Google grants stand-alone projects
   * allow-top-navigation-by-user-activation, which bound projects never get, so if
   * a standalone deployment redirects cleanly it is worth having.
   *
   * Paste your response spreadsheet's URL and run this once. Everything else works
   * unchanged, because the dispenser already opens the sheet by stored ID rather
   * than assuming an active one.
   *
   * The submit-side backstop still has to live in the BOUND script, since only a
   * bound project can hold the form-submit trigger. Running both is fine.
   */
  function vyUseSpreadsheet(url) {
    const target = url || 'PASTE_YOUR_SPREADSHEET_URL_HERE';
    const m = String(target).match(/\/spreadsheets\/d\/([a-zA-Z0-9-_]+)/);
    if (!m) {
      Logger.log('Could not read a spreadsheet ID from: ' + target +
                 '\nCall it like: vyUseSpreadsheet("https://docs.google.com/spreadsheets/d/..../edit")');
      return;
    }
    PropertiesService.getScriptProperties().setProperty('VY_SS_ID', m[1]);
    const ss = SpreadsheetApp.openById(m[1]);
    Logger.log('Dispenser now points at: ' + ss.getName());
    Logger.log('Dispenser URL: ' + (vyDispenserUrl_() || 'not deployed yet'));
  }

  /** Prints how much of the pool is left. Run any time. */
  function vyPoolStatus() {
    const ss = SpreadsheetApp.getActiveSpreadsheet();
    const pool = ss.getSheetByName(VY.poolTabName);
    if (!pool) { Logger.log('No pool tab named "' + VY.poolTabName + '".'); return; }
    const c = vyCountCodes_(pool);
    Logger.log('Codes: ' + c.total + ' total | ' + c.unused + ' unused | ' +
               c.issued + ' issued but not submitted | ' + c.used + ' used.');
    Logger.log('Dispenser: ' + (vyDispenserUrl_() || 'not deployed'));
  }
  ```
</Accordion>

## What happens next

<div>
  <a href="/learn/what-your-users-see">
    <span>
      <Icon icon="mobile-screen" />
    </span>

    <span>
      <Icon icon="mobile-screen" />
    </span>

    <span>What your respondent sees</span>
    <span>See exactly what your respondent sees.</span>
  </a>

  <a href="/docs/guides/pre-generated-passwords">
    <span>
      <Icon icon="layer-group" />
    </span>

    <span>
      <Icon icon="layer-group" />
    </span>

    <span>The same mechanism, any platform</span>
    <span>One password per human. Spend it once, wherever your study lives.</span>
  </a>
</div>


# Overview
Source: https://docs.verifyyou.com/docs/guides/pre-generated-passwords

One single-use code per human, good exactly once.

## One password per person

Anything you hand out on a link can be forwarded, shared, and taken twice. A survey, a giveaway, a beta invite, an event registration, a claim form. The link cannot tell a real first-timer from the same person on a second browser.

It bites hardest in market research and academic panels. Bots, duplicate respondents, professional survey-takers and survey farms clear a simple screener and land in your data, so you pay for completes that are not real and clean it up afterward. HumanCheck moves the check upstream, before your first question, so only a real, unique, present human ever reaches it.

One idea holds the whole thing up: **every password is tied to one unique human and works exactly once.**

<div>
  <div>
    <div>
      <button><span>1</span><span>A passcode per human</span></button>
      <button><span>2</span><span>Fakes locked out</span></button>
      <button><span>3</span><span>Clean data</span></button>
    </div>

    <div>
      <div />

      <div>
        <span>1</span>
        <p>Each verified person receives a one-time passcode, created for their face alone and dropped onto their link. It fills itself in when they arrive.</p>

        <div>
          <div><span><Icon icon="lock" /></span>One-time passcode</div>
          <div><span>vyp\_k2•••••••4qt</span><span><Icon icon="circle-check" /></span></div>
          <div>Filled in from their link. Works exactly once.</div>
        </div>
      </div>

      <div>
        <span>2</span>
        <p>A bot never earns a passcode, because it cannot pass a live face check. The same face never earns a second one. And each passcode works exactly once, so a forwarded or shared one is already spent.</p>

        <div>
          <div>
            <span>
              <Icon icon="user" />
            </span>

            <svg>
              <path />

              <path />
            </svg>

            <span><span><Icon icon="check" /></span>Through</span>
          </div>

          <div>
            <span>
              <Icon icon="robot" />
            </span>

            <svg>
              <path />

              <path />
            </svg>

            <span><span><Icon icon="xmark" /></span>Blocked</span>
          </div>

          <div>
            <span>
              <Icon icon="user-group" />
            </span>

            <svg>
              <path />

              <path />
            </svg>

            <span><span><Icon icon="xmark" /></span>Same face, second try</span>
          </div>
        </div>
      </div>

      <div>
        <span>3</span>
        <p>Only real, first-time people get through. Everyone else stops at the check, so there is nothing to clean up afterwards.</p>

        <div>
          <div><span>rsp\_78421</span><span>Verified</span></div>
          <div><span>rsp\_78422</span><span>Blocked</span><span><Icon icon="xmark" /></span></div>
          <div><span>rsp\_78424</span><span>Verified</span></div>
        </div>
      </div>

      <div>
        <span />
      </div>
    </div>

    <div>
      <img alt="" />

      <button aria-label="Previous stage">
        <svg>
          <path />
        </svg>
      </button>

      <button aria-label="Next stage">
        <svg>
          <path />
        </svg>
      </button>
    </div>
  </div>
</div>

## Why the gate holds

Each password is a claim ticket. We only hand one to a person who just proved, on camera, that they are **live** and **unique**. Your survey platform enforces the ticket with its own built-in gate: Alchemer's <a href="https://help.alchemer.com/help/login-password-action">Login/Password action</a>, or Qualtrics' Authenticator, set to individual one-time passwords that deactivate after use. Your platform's feature, your platform's wording.

So every cheap trick fails: a shared link carries a spent password, a guessed password does not exist, a bot never earns one, and the same face can never get a second one for the same thing, on any device.

One honest limit: the check proves a real, unique human, and says nothing about how carefully they answer. Keep your speeder and attention checks.

## What we never touch

No photo is shared with you or with the platform on the other end, only a yes or no. You receive a verdict and a password, never a face, a name, or personal information.

## What it costs

Pricing depends on your volume and your use case. Tell us what you are running and we will give you a number. Blocked traffic never enters your data.

## Set it up on your platform

Four platforms have a full step-by-step guide. Pick yours and follow it, no code on any of them.

<CardGroup>
  <Card title="Qualtrics setup" icon="sliders" href="/docs/guides/qualtrics">
    Five steps, no code.
  </Card>

  <Card title="Alchemer setup" icon="sliders" href="/docs/guides/alchemer">
    Five steps, no code.
  </Card>

  <Card title="Google Forms setup" icon="table" href="/docs/guides/google-forms">
    Five steps, with a script for the response sheet.
  </Card>

  <Card title="Tally setup" icon="clipboard-list" href="/docs/guides/tally">
    Five steps, with a webhook.
  </Card>
</CardGroup>

## Works on more than these four

Nothing about the mechanism is specific to one platform. The check and the single-use credential are always the same; only the platform's own lock changes shape to fit. So the gate works anywhere you can hand each respondent a link or password that works exactly once.

| Platform                  | The credential               | The platform's own lock                                                                                |
| ------------------------- | ---------------------------- | ------------------------------------------------------------------------------------------------------ |
| **Qualtrics**             | A one-time code on the link  | The Authenticator in Survey Flow, where each code authenticates exactly once                           |
| **Alchemer**              | A one-time password          | The Login/Password action, individual one-time passwords that deactivate after use                     |
| **Tally**                 | A one-time token on the link | A hosted gate opens the form only for a valid token, and a webhook removes anything that slips through |
| **Typeform, Jotform**     | A one-time token on the link | The same hosted gate, no guide written yet                                                             |
| **Google Forms**          | A one-time token in a field  | A small script checks each submission and removes the ones without a valid token                       |
| **Your own survey stack** | A one-time token             | Your code asks us whether a token is real and unused before it saves the response                      |

The strength of the lock varies a little by platform. Qualtrics and Alchemer enforce it server-side before a single question shows, which is why those two came first, but the hosted wrapper plus uniqueness protect every platform. We are actively building out more guides.

**Not sure about your platform?** At the top of this page, open the **Copy page** menu and pick **Open in Claude** or **Open in ChatGPT**. It carries this page across, including the table above, so you can ask whether HumanCheck works with your tool and get an answer grounded in how the gate actually works.

Curious what the respondent goes through? See [what your users see](/learn/what-your-users-see).


# Qualtrics setup
Source: https://docs.verifyyou.com/docs/guides/qualtrics

Put HumanCheck in front of your Qualtrics study. Five steps, no code.

<Steps>
  <Step title="Create your study">
    In Qualtrics, exactly as you normally would.

    1. Build your study as usual. Your questions stay exactly where they are.
    2. You add the gate in the **Survey Flow**, not on a page, so nothing about your instrument changes.

    <p><strong>You now have:</strong> a normal Qualtrics study.</p>
  </Step>

  <Step title="Connect your study in VerifyYou">
    In your [VerifyYou dashboard](https://platform.verifyyou.com/dashboard/verifications), open a verification and go to the **Integration** tab.

    1. Make sure the method is **One-time passwords**. If it is set to something else, click **Switch method** and choose it.
    2. Under **Your survey platform**, pick **Qualtrics**.
    3. Paste your **Qualtrics survey link**.
    4. Set **how many one-time passwords** you need, one per expected respondent. You can always generate more later.
    5. Click **Connect survey**. We generate your passwords and hand back your study link.

    <p><strong>You now have:</strong> your <strong>study link</strong> (share this one, not your Qualtrics link) and your <strong>one-time passwords</strong>. Click **Copy list** to copy them for the next step.</p>

    <Frame>
      <img alt="VerifyYou Integration tab, connect a survey platform" />
    </Frame>

    <Frame>
      <img alt="VerifyYou study link ready with copy list" />
    </Frame>
  </Step>

  <Step title="Create a contact list and paste your passwords">
    In Qualtrics's **Contacts** (called **XM Directory** on newer accounts).

    1. Create a new contact list and choose **Manual input**.
    2. Paste the one-time passwords you copied into the **External data reference** column, one per row. That column is the passcode slot: paste them under any other field and the gate will not pick them up.

    <p><strong>You now have:</strong> a contact list where each code sits in External data reference and can authenticate exactly once.</p>

    <Frame>
      <img alt="Qualtrics contact list manual input, External data reference column" />
    </Frame>
  </Step>

  <Step title="Add the gate in Survey Flow">
    Open your study's **Survey Flow**.

    1. Add a **Set Embedded Data** element at the very top, with the single field `vypw` and no value. Qualtrics fills it from each respondent's link, their documented [query-string mechanism](https://www.qualtrics.com/support/survey-platform/survey-module/survey-flow/standard-elements/passing-information-through-query-strings/), so it should read "Value will be set from Panel or URL."
    2. Add an **Authenticator** beneath it, which shows as **Branch on Successful Authentication**. Set **Authentication Type** to **Contact**, authenticate using **the contact list you just created**, set the authentication field to **External Data Reference**, tick **Pre-fill**, and enter `vypw`. Leave **"Allow authenticating respondents to retake authenticated section"** unchecked, which is the default: that is what makes each code one-time.
    3. Put your survey blocks inside the authentication branch.
    4. Add a second **Branch** ending in its own **End of Survey**, for anyone who does not authenticate. Qualtrics records a failed authentication as a complete by default, so this branch is what keeps failed and duplicate visitors out of your data.

    Qualtrics's own [Authenticator](https://www.qualtrics.com/support/survey-platform/survey-module/survey-flow/advanced-elements/authenticator/) enforces the gate, and with Pre-fill a respondent with the right credentials "never even sees the authenticator."

    <p><strong>You now have:</strong> a gate that opens itself for verified respondents and routes everyone else to a screen-out.</p>

    <Frame>
      <img alt="Qualtrics Survey Flow with embedded data and authentication branch" />
    </Frame>

    <Frame>
      <img alt="Qualtrics authentication field, External Data Reference with Pre-fill" />
    </Frame>
  </Step>

  <Step title="Share your VerifyYou link, not your Qualtrics link">
    The link you hand out is the **study link from VerifyYou** (the `app.verifyyou.com/verification/...` one, from **Copy** in the dashboard), never your Qualtrics link. This is the whole point: the VerifyYou link sends every respondent through the face check first, then redirects the verified ones into your Qualtrics study with their one-time password already attached. Anyone who opens the raw Qualtrics link skips the check, so only ever share the VerifyYou link, in your panel, your sample provider, or your invite email.

    <p><strong>You now have:</strong> a fielded study where everyone who reaches your questions came through the check. That's the whole setup.</p>
  </Step>
</Steps>

<Note>
  **License note.** Free Qualtrics accounts do not include contact lists, so this flow needs a standard or university license, which is what most institutions provide. If the Authenticator element does not appear in your Survey Flow options, your Qualtrics brand administrator can enable it.
</Note>

## What happens next

<div>
  <a href="/learn/what-your-users-see">
    <span>
      <Icon icon="mobile-screen" />
    </span>

    <span>
      <Icon icon="mobile-screen" />
    </span>

    <span>What your respondent sees</span>
    <span>See exactly what your respondent sees.</span>
  </a>

  <a href="/docs/guides/pre-generated-passwords">
    <span>
      <Icon icon="layer-group" />
    </span>

    <span>
      <Icon icon="layer-group" />
    </span>

    <span>The same mechanism, any platform</span>
    <span>Alchemer and Qualtrics today. The same pattern works anywhere.</span>
  </a>
</div>


# Tally setup
Source: https://docs.verifyyou.com/docs/guides/tally

Put HumanCheck in front of your Tally form. Five steps, no code.

Tally cannot ask an outside service anything while a respondent is looking at your form, so nothing inside Tally can tell a real password from an invented one. No form builder setting does this: the form password is a single shared secret, and the duplicate rule only asks whether a value has been seen before, never whether it is one of ours. So HumanCheck holds the line in three places instead of one.

The check happens on our side, before anyone reaches your form. Your form turns away anyone arriving without a password that looks like one of ours, and Tally's own duplicate rule makes sure no password is spent twice. Then, on our side again, anything that reached your results with a password we never issued is removed. Only the last of those knows what your real passwords are, which is why it is the one that decides what stays.

<Note>
  Somebody who skipped the check can still open your form and press submit. What they cannot do is leave a trace in your data or get paid for it. If you need unverified people to be unable to load the page at all, [Qualtrics](/docs/guides/qualtrics) and [Alchemer](/docs/guides/alchemer) can do that and Tally cannot. Tally does have a password setting that hides the form until a password is typed, but it is one password for the whole study rather than one per person, and it cannot be filled in from a link, so it costs every respondent a copy and paste. Ask us if your link is going somewhere public and it is worth the trade.
</Note>

<Steps>
  <Step title="Build your form">
    In Tally, exactly as you normally would, with two additions.

    1. Type `/hidden` anywhere in the editor to insert a **Hidden field** block, and name the field `vypw`, in lower case. This is where each respondent's password arrives from their link. Tally's [hidden fields](https://tally.so/help/hidden-fields) are case sensitive, so the spelling has to match exactly.
    2. Add a **Short answer** question called **Verification code** as the first question, and mark it **Required**. Underneath it, write something like "Filled in automatically, please leave this alone."
    3. Click the handle to the left of that question, switch on **Default answer**, and pick the `vypw` hidden field from the dropdown. This is the step that makes the whole thing invisible: the password fills the box on its own, and a verified respondent types nothing.
    4. Put a **page break** straight after it, so the code box is alone on page one and your questions start on page two. Tally only acts on a page jump when somebody presses Next, so the screen-out in the next step will not fire unless the code box has a page of its own.
    5. At the end of the form, add two **thank you** pages: first the one people see when they finish, then a second one saying they need to start from their invitation link. Order matters, the first thank you page is where a normal finisher lands.
    6. Click **Publish**.

    The visible question is doing real work. A hidden field on its own can be left empty by anyone who opens your form directly, and Tally will accept that submission, and the next one, and the one after that. A required question cannot be left empty.

    <p><strong>You now have:</strong> a form whose first question is a code box that fills itself in.</p>
  </Step>

  <Step title="Turn away anything that is not a password">
    Two settings, both free, both in your published form.

    1. On the **Verification code** question, add conditional logic: **if** the answer **does not start with** `vyp_`, **jump to** the second thank you page, the one about starting from the invitation link. Anyone who wandered in without a password stops there instead of filling in your study.
    2. In **Settings**, under **Access**, turn on **Prevent duplicate submissions** and choose the **Verification code** question as the unique identifier. Not IP address and not Respondent ID: those can be worked around by switching network or browser.

    Tally's [duplicate rule](https://tally.so/help/prevent-duplicate-submissions) now runs on their servers before a response is stored, so Tally turns away a second attempt carrying a spent password with "Form submission not accepted. It looks like you have already filled out this form." What it does not do is check that a password came from us, because Tally has no way to know what your passwords are. That is the next two steps.

    One thing to expect in your results: somebody who is screened out here still leaves a row, carrying whatever they typed in the code box and none of your survey answers. It is removed in step four, and until then it is obvious what it is.

    <p><strong>You now have:</strong> a form that accepts each password exactly once and turns away anything that is not shaped like one.</p>
  </Step>

  <Step title="Connect your study in VerifyYou">
    In your [VerifyYou dashboard](https://platform.verifyyou.com/dashboard/verifications), open a verification and go to the **Integration** tab.

    1. Make sure the method is **One-time passwords**. If it is set to something else, click **Switch method** and choose it.
    2. Set **how many one-time passwords** you need. Ask for at least twenty percent more than the respondents you expect. Passwords cost nothing, and running out mid-study screens out real people.
    3. Send us your Tally form link. We give you back a **gate link** for this study. That is where we hand a verified respondent their password.
    4. Set the destination for verified people to that **gate link**.

    <p><strong>You now have:</strong> your <strong>study link</strong>, which is the one you share, and a gate link doing the handover.</p>
  </Step>

  <Step title="Connect the webhook">
    In your published form's **Integrations** tab.

    1. Find **Webhooks** and click **Connect**.
    2. Paste the **endpoint URL** we gave you with your gate link.
    3. Paste the **signing secret** we gave you alongside it. That secret is how the endpoint knows a submission really came from your form.
    4. Save.

    Tally now tells us about every submission as it lands, and this is the step that checks a password against the ones we actually issued. A submission carrying a real, unused password is left alone. One carrying a password we never issued is removed from your results, and so is one that arrived with no password at all. [Webhooks](https://tally.so/help/webhooks) are free on every Tally plan.

    <p><strong>You now have:</strong> a study where a response has to arrive with a password we issued in order to stay in your results.</p>
  </Step>

  <Step title="Share your VerifyYou link, not your Tally link">
    The link you hand out is the **study link from VerifyYou** (the `app.verifyyou.com/verification/...` one, from **Copy** in the dashboard), never your Tally link. This is the whole point: the VerifyYou link sends every respondent through the face check first, then redirects the verified ones into your Tally form with their one-time password already attached. Anyone who opens the raw Tally link skips the check, so only ever share the VerifyYou link, in your panel, your sample provider, or your invite email.

    <p><strong>You now have:</strong> a fielded study where everyone who reaches your questions came through the check. That's the whole setup.</p>
  </Step>
</Steps>

## Two settings worth leaving alone

Keep **partial submissions** off, so an abandoned attempt does not sit in your results looking like a response. And if you know the size of your sample, set a **submission limit** to match the number of passwords you asked for, so a study that has finished closes itself rather than collecting stragglers.

## When something looks wrong

<AccordionGroup>
  <Accordion title="Real respondents are being told they have already filled out the form">
    Two passwords ended up the same, or somebody is on a link they already used. Check the **Prevent duplicate submissions** setting is pointed at `vypw` and not at Respondent ID, which would block a second person on a shared computer.
  </Accordion>

  <Accordion title="Responses are arriving with the code box empty">
    The hidden field is spelled differently from the one on the link. It has to be exactly `vypw`, in lower case. Tally hidden fields are case sensitive, so `VYPW` or `vyPW` silently collects nothing, and the default answer on your Verification code question then has nothing to copy.
  </Accordion>

  <Accordion title="Nothing is being removed from my results">
    The webhook is not connected, or it is connected without the signing secret. Open the **Integrations** tab, click the clock icon next to your webhook, and look at the events log: it shows every request and the response it got back.
  </Accordion>

  <Accordion title="I have run out of passwords mid-study">
    Ask us for more and we add them to the same pool. Nothing about your form changes, and the respondents already holding a password keep it.
  </Accordion>
</AccordionGroup>

## What happens next

<div>
  <a href="/learn/what-your-users-see">
    <span>
      <Icon icon="mobile-screen" />
    </span>

    <span>
      <Icon icon="mobile-screen" />
    </span>

    <span>What your respondent sees</span>
    <span>See exactly what your respondent sees.</span>
  </a>

  <a href="/docs/guides/pre-generated-passwords">
    <span>
      <Icon icon="layer-group" />
    </span>

    <span>
      <Icon icon="layer-group" />
    </span>

    <span>The same mechanism, any platform</span>
    <span>Tally today. The same pattern works anywhere.</span>
  </a>
</div>


# Cross-network recognition
Source: https://docs.verifyyou.com/docs/how-it-works/cross-network-recognition

Recognizing somebody who verified on another platform.

Every HumanCheck runs on one shared network. When somebody passes a check on any platform using HumanCheck, their face vector is on the network, so the next platform can recognise that person and see if they have been flagged. Every platform that joins makes the network of verified humans stronger, and everyone in it better protected.

## What it gives you

* A person verified elsewhere can be recognized on your check without scanning again
* You still get the same verdict, a real and unique human, without paying for their friction
* If we have seen that person flagged somewhere else in the network, we tell you

## What decides how much they are asked

Your own configuration decides. Whether a recognized person walks straight through, re-verifies on a cadence, or scans every time comes from your **Verification limit** and **Skip check on known devices**. See [Configuration](/docs/verifications/configuration).

A stricter setting on your platform changes nothing about anyone else's, and theirs changes nothing about yours.

<Note>
  Skipping the scan saves the person friction, not you a verification. A returning guest who passes without scanning still counts as one.
</Note>

**Next:** [Security and privacy](/docs/how-it-works/security-and-privacy)


# Guests and members
Source: https://docs.verifyyou.com/docs/how-it-works/guests-and-members

How we recognize somebody who comes back.

Everybody who takes a check is a **guest**. A guest who proves a phone or email during the check becomes a **member**, and that is what lets us know them anywhere.

## Guests

Known by the device ID in their browser, and nothing else. No phone, no email, no name.

On that same device, inside the window you set under **Skip check on known devices**, they come straight back through. On a new device or a cleared browser we have no way to tie them to their last visit, so they take the check again. The face still matches, so if your settings only allow one pass, that second attempt is a collision rather than a welcome back.

## Members

Proved a phone or email during the check, with a one-time code, so ownership was established rather than typed in.

That claim travels with them. On a new device their face is matched, they confirm with the same number or email, and they carry on.

This is the argument for asking for one. Bind repeat visitors and they are recognised wherever they turn up; leave them anonymous and every new device looks like a new person.

## What your integration sends

Three ways to start a session, and each one changes what comes back.

An **`external_id`**, when you already hold an account for them. Duplicates are reported against your own id, which makes results join straight onto your user table.

An **email or phone**, for a new signup. The run is bound to that identity and the person cannot swap it.

**Nothing**, for an anonymous check. A session and a pass, with no identity attached.

## Where it stops

We can tell you this is the same human as before, and whether we have seen them elsewhere in the network. We cannot tell you their name. Nothing here is an identity check. See [Cross-network recognition](/docs/how-it-works/cross-network-recognition) and [Security and privacy](/docs/how-it-works/security-and-privacy).

**Next:** [Cross-network recognition](/docs/how-it-works/cross-network-recognition)


# Security and privacy
Source: https://docs.verifyyou.com/docs/how-it-works/security-and-privacy

Information for a security review.

We answer one question: is there a real, unique, live human on the other end. We hold as little about that person as we can while doing it.

We let you opt in or out of PII, so you choose your level of liability. **Identity** on each verification decides whether the check asks for a phone or email or asks for neither. Contact our team for more on what that means for your setup, and see [Configuration](/docs/verifications/configuration).

## Security documentation

Our current security documentation is available on request, and we will work through your vendor questionnaire with you. Tell us what your review needs at [security@verifyyou.com](mailto:security@verifyyou.com).

To report a vulnerability, use the same address, and give us a reasonable window to fix it before any public disclosure.

**Next:** [Gate a signup](/docs/use-cases/signup-gate)


# Docs
Source: https://docs.verifyyou.com/docs/index

How to run HumanCheck, screen by screen.

New here? Start with [Intro to VerifyYou](/learn/intro-to-verifyyou).

<Columns>
  <Card title="Start guide" icon="rocket" href="/docs/get-started/getting-access">
    Get a workspace, and run your first check.
  </Card>

  <Card title="Verifications" icon="badge-check" href="/docs/verifications/creating-a-verification">
    Make a check, set what it does, and put it in front of people.
  </Card>

  <Card title="Activity" icon="wave-pulse" href="/docs/activity/reading-activity">
    See who came through, open anyone, and take the list away.
  </Card>

  <Card title="Insights" icon="chart-column" href="/docs/insights/reading-insights">
    Watch how your traffic moves week to week.
  </Card>

  <Card title="Workspace" icon="users" href="/docs/workspace/team-and-roles">
    Add your colleagues, and take them off again.
  </Card>

  <Card title="Concepts" icon="gears" href="/docs/how-it-works/guests-and-members">
    How we recognize a human who comes back.
  </Card>

  <Card title="Security" icon="shield-halved" href="/docs/how-it-works/security-and-privacy">
    What we hold, what you can opt out of, and who to ask for a review.
  </Card>

  <Card title="Use cases" icon="list-check" href="/docs/use-cases/signup-gate">
    Gate a signup, gate a payout, or sweep the accounts you already have.
  </Card>

  <Card title="Guides" icon="clipboard-list" href="/docs/guides/pre-generated-passwords">
    Give each person a password that works once. Four platforms, step by step.
  </Card>

  <Card title="Glossary" icon="book" href="/docs/glossary">
    Look up any word we use.
  </Card>
</Columns>


# Flags
Source: https://docs.verifyyou.com/docs/insights/flags

Top users to investigate.

**Flags** is every person our own checks caught on this verification, one row per flag. It is scoped to your traffic: what somebody did on another platform in the network does not appear here.

## Reading the list

<Frame>
  <img alt="Flags tab showing family chips and flagged rows" />
</Frame>

Each row carries the identifier, what we caught in plain language, the kind of flag, the trust band and score, the result, and how long ago it settled.

The reasons are written to be read rather than decoded. `VPN exit in Lagos, NG`. `2 accounts share this face`. When the flag is about accounts, the row names the other accounts, which is usually enough to act without opening anything.

One person can hold several flags. Somebody arriving through a VPN on a face that is already on another account appears twice, once for each.

## Narrowing it

Chips across the top split the list by family, **Network**, **Geography** and **Accounts**, each with its own count, and bars underneath show the split at a glance. **Export** takes whatever you are looking at.

## Opening one

<Frame>
  <img alt="Flag detail view for a VPN exit" />
</Frame>

Click a row and you get the flag explained: what we saw, and for a network flag a map of where the connection surfaced. It ends on the final trust and the result, with **View profile** and **Confirmation history** to go further.

These views are careful about what they claim. A VPN flag says the exit point is where the connection surfaced and not necessarily where the person is, which is the honest reading and the one to repeat to your own team.

## A low score is not a flag

They answer different questions. On the live account this was checked against, a person carries a trust score of 45 and a **Denied** result with nothing flagged at all.

The score counts signals collected on the way through. A flag is a specific thing we caught. The result is your configuration acting. Denied with nothing flagged usually means a rule of yours fired, like the verification limit, rather than anything being wrong with the person.

## When to come here

Come to Flags when you have nobody particular in mind and want to know whether anything needs you. An accounts flag means one face is on more than one account, which is a collision, and [Configuration](/docs/verifications/configuration) decides what happens when one is found. Go to [Reading Activity](/docs/activity/reading-activity) when you already have somebody, or to slice the whole population by country, network or collisions.

**Next:** [Reading Insights](/docs/insights/reading-insights)


# Reading Insights
Source: https://docs.verifyyou.com/docs/insights/reading-insights

Outcomes and threat activity across a period.

[**Insights**](https://platform.verifyyou.com/dashboard/insights) is an aggregated view of all the people running through your verification flows. Activity shows you one person at a time; this shows you the shape of everybody.

The period picker at the top drives the charts and counts.

<Frame>
  <img alt="The Insights page, showing the Settled Passes, Liveness Pass Rate and Elevated Risk cards above the threat levels chart" />
</Frame>

## Outcomes

**Settled Passes** counts every run that reached a decision in the period. It is your volume: what the check actually processed.

**Liveness Pass Rate** is the share who proved a live face on capture. Watch it for friction rather than fraud. When it falls, the usual causes are lighting, cameras and where your traffic is coming from.

**Elevated Risk** is how many people scored into the elevated or high bands, shown against the number of scored passes so you read it as a share of your traffic rather than a raw count.

## Threat activity

**Threat levels over time** stacks your scored sessions by day in four bands from Low to High, so you can see whether a bad day is a spike or a trend.

**Top threat signals** shows what is firing most across scored sessions. Accounts dominating means the same people are coming back. Automation dominating means scripts. Network dominating means proxies and datacenter traffic. Each row opens the matching flags list, and **Go to flags** takes you to all of them.

**Top bad actors** ranks the riskiest flagged people, lowest trust first, each with their result, the families they tripped and their score. When you want a list of people to work rather than a number, start here.

## Who is arriving

**Session attributes** gives the top five countries, platforms, device types and browsers. Look at it when nothing is wrong, so you know what your normal looks like. If your traffic is normally ninety percent one country, the week it is not is the week to look.

**People** covers capture outcomes and the estimates we make: liveness passed against failed, an age range, gender.

**Risk flags** gives the share of people arriving with each of VPN, Datacenter IP, Tor exit, Abuse-listed IP, TLS automation and Fingerprint mismatch raised. This is the one panel where a number does not open into people, so take the finding into [Activity](/docs/activity/reading-activity) and filter for the same thing.

**Next:** [Threat levels and signals](/docs/insights/threat-levels-and-signals)


# Threat levels and signals
Source: https://docs.verifyyou.com/docs/insights/threat-levels-and-signals

How the trust score and the threat bands relate.

A person carries a trust score out of 100, where a high number is good. Insights sorts the same sessions into threat bands, where a high band is bad. They measure the same thing from opposite ends.

## The trust score

Everyone starts at 100. Anything suspicious we detect during the check subtracts from it, and the size of the deduction follows how suspicious the thing is. A clean run keeps its 100. A run arriving through a datacenter IP on a face that is already on two other accounts does not.

So the score is a summary of what we found, not a judgement of the person, and it is worth reading as a prompt: the lower it goes, the more there is to look at. Your configuration decides whether they passed or failed. The score does not.

## The threat bands

The same sessions, grouped for the population view: **Low**, **Moderate**, **Elevated**, **High**. Higher means more of concern, which runs the opposite way to the score.

A person with a high trust score sits in a low threat band. Both describe the same run.

## The threat families

**Top threat signals** on Insights groups what fired into five families.

**Network** is where the connection came from: a VPN, a datacenter, a Tor exit, an IP already known for abuse.

**Geography** is where they appear to be, and whether that fits what you or we expected.

**Accounts** is one face turning up on more than one account. This is the family people act on most.

**Automation** is whether the session behaves like a real browser or like a script, read from how the connection presents itself.

**Liveness** is the capture itself: failed attempts, low confidence, a screen held up to the camera.

Which family dominates tells you what you are dealing with, and it is a different question from how much of it there is.

**Next:** [Team and roles](/docs/workspace/team-and-roles)


# Gate key actions
Source: https://docs.verifyyou.com/docs/use-cases/gate-key-actions



You verify somebody once, at signup. The money moves later, and usually more than once. Here's how we put a check on the moment itself with HumanCheck:

1. **The check runs at the action, not at signup.** The account already exists. The check sits in front of the checkout, the payout, the survey completion or the drop, and the action completes once it settles.
2. **People you have already verified are recognized.** Most of them go through without scanning again, so the friction lands on the people you have not seen before.
3. **The limit matches the action.** *Once per lifetime* for something meant to go once per person, *once per period* for a weekly payout, *unlimited* for a checkout where you only need a live human present.
4. **Put it where the incentive is.** A face scan in front of a one dollar survey costs you completes, because there is another survey paying a dollar that does not ask. The same scan in front of the payout does not, because the person is about to be paid and has a reason to finish it.
5. **The outcome is yours to set.** *Block* turns the second attempt away. *Allow + flag* lets it through and records it for your team.

This covers the action. For the account behind it, see [Gate a signup](/docs/use-cases/signup-gate).

## How you start

1. Create a verification for the action. One workspace runs several at once, each with its own settings, so a payout gate can be strict while a checkout stays light.
2. Set **Verification limit** to match the action.
3. Set **On collision** to *Block* where one per person is the rule, or *Allow + flag* where a duplicate is a judgement call.
4. Put it in the flow. Paste the no-code link, or use the SDK and confirm the result on your server before the action completes.
5. Run it on test keys first, and watch the completion rate on the first batch before you widen it.

## Next steps

<CardGroup>
  <Card title="One-time passwords" icon="clipboard-list" href="/docs/guides/pre-generated-passwords">
    A worked example, with setup for four survey platforms.
  </Card>

  <Card title="Configuration" icon="sliders" href="/docs/verifications/configuration">
    Set what the check does.
  </Card>

  <Card title="Integration" icon="code" href="/docs/verifications/integration">
    The no-code link, or the SDK.
  </Card>

  <Card title="Guests and members" icon="users" href="/docs/how-it-works/guests-and-members">
    How recognition carries across your checks.
  </Card>
</CardGroup>


# Persistent verification
Source: https://docs.verifyyou.com/docs/use-cases/persistent-verification



Multi-factor proves somebody holds a credential. It cannot tell you they did not hand that credential to somebody else. Here's how we check the same human is still there with HumanCheck:

1. **The first check sets the baseline.** Run one as early as you can, at signup or when somebody completes a profile, and every later check compares against that face.
2. **Every later check asks whether this is the same person.** If it is, they are recognized and pass. If somebody else is holding the account, the run does not tie back to the person who opened it, and the history shows two people where you expected one.
3. **Recognition carries across your checks.** Somebody verified at signup is recognized at payout, so the second check is a few seconds.
4. **You choose the moments.** A payout, a withdrawal, a high value action, or a fixed interval. Each is its own verification with its own settings.
5. **The history sits on the person.** Every confirmation they appear in, newest first, with the devices we know them on and what they have proven.

This tells you whether it is the same person, not who they are. To sweep the accounts you already have once, see [Userbase healthcheck](/docs/use-cases/userbase-fraud-audit).

## How you start

1. Create the baseline verification and put it as early in the account's life as friction allows.
2. Set **Identity** to *Linked by guest*, so a phone or email carries recognition when somebody changes device.
3. Create a second verification for the recurring moment, and set its **Verification limit** to that cadence, for example *once per period*.
4. Turn on **Skip check on known devices** if you would rather people on a device you already know pass without scanning.
5. Read **History** on the person, which lists every confirmation they appear in.

## Next steps

<CardGroup>
  <Card title="Guests and members" icon="users" href="/docs/how-it-works/guests-and-members">
    How recognition carries across devices and checks.
  </Card>

  <Card title="Configuration" icon="sliders" href="/docs/verifications/configuration">
    Every setting on a check.
  </Card>

  <Card title="Comprehensive trust score" icon="id-card" href="/docs/activity/guest-profiles">
    The person view, and the history behind it.
  </Card>

  <Card title="Cross-network recognition" icon="share-nodes" href="/docs/how-it-works/cross-network-recognition">
    Recognition beyond your own workspace.
  </Card>
</CardGroup>


# Gate a signup
Source: https://docs.verifyyou.com/docs/use-cases/signup-gate



There's no limit to how many emails or devices a human can own, but they cannot replace their face. Here's how we limit each person to one account with HumanCheck:

1. **A live person has to be there.** A photo held up to the lens, a recorded video, or a script never gets past this one.
2. **The first account through owns that face.** The scan becomes a face vector, a numerical representation of the face's geometry. Whoever signed up first keeps their account, and nothing here touches them again.
3. **A second signup with that face is recognized as the same person**, whatever email or login they use this time. That holds across your other checks too.
4. **You decide what happens to the second account.** Refuse it, and they are told an account already exists. Or let it through and have the person flagged for your team. The setting is **On collision**.
5. **Ask for a phone or an email.** Set that way, the same person is recognized wherever they sign up from, so a new phone changes nothing. Left anonymous, recognition stays with the device they used, which suits a one-off check and not a signup.

A gate only covers new signups. For the accounts you already have, see [Userbase healthcheck](/docs/use-cases/userbase-fraud-audit).

## How you start

1. Create a verification and pick the **Signup Gate** preset.
2. Set **Identity** to *Linked by guest*, which is the phone or email in point five.
3. Set **Verification limit** to *Once per lifetime*, so one person gets one account, and **On collision** to *Block*.
4. Paste the no-code link into your signup, or use the SDK and confirm the result on your server.
5. Run it on test keys first. The simulator behaves like the real check, and the test people it creates stay separate from your live records.

## Next steps

<CardGroup>
  <Card title="Configuration" icon="sliders" href="/docs/verifications/configuration">
    Set what the check does, including denials.
  </Card>

  <Card title="Integration" icon="code" href="/docs/verifications/integration">
    The no-code link, or the SDK.
  </Card>

  <Card title="Reading Activity" icon="wave-pulse" href="/docs/activity/reading-activity">
    Who reached the gate, and who was refused.
  </Card>

  <Card title="Guests and members" icon="users" href="/docs/how-it-works/guests-and-members">
    How recognition carries across your checks.
  </Card>
</CardGroup>


# Userbase healthcheck
Source: https://docs.verifyyou.com/docs/use-cases/userbase-fraud-audit



Nothing in your own data proves two accounts are one person. A face does. Here's how we find the duplicates already inside your userbase with HumanCheck:

1. **The check goes to accounts you already have.** Somebody who is who they say they are passes in seconds. Somebody who is not has to explain why they cannot, which your own records were never going to tell you.
2. **Two accounts with one face come back as one person.** Whoever verified first holds that face, and the later account is tied to it, whatever email sits on it.
3. **Everyone who passes leaves a location and a network trail.** VPN, datacenter IP, Tor exit, abuse-listed IP, TLS automation and fingerprint mismatch each land against the person, next to where they verified from, so you can hold it against the country on file.
4. **Flag, do not block.** An audit is not a door. Set the duplicate action to allow and flag, so nobody paying you is locked out while you decide.
5. **You act in your own system.** Export carries the results with the `external_id` you attached, so you can line a flagged person up against the account you already hold.

Run it on the clock you already work to. If payouts go out on a Tuesday, an audit that lands on Wednesday cost you the week. A sweep is a snapshot. To ask the same question at the same moment forever, see [Persistent verification](/docs/use-cases/persistent-verification). For new accounts, see [Gate a signup](/docs/use-cases/signup-gate).

## How you start

1. Create a verification and pick the **Account Sweep** preset.
2. Decide how results tie back to your accounts. **No code**: send to the addresses you already hold and set **Identity** to *Linked by guest*, so the email links that face to that account. **Code**: set it to *Provided by you* and pass the identifier you already keep.
3. Set **On collision** to *Allow + flag*.
4. Send from the verification's **Activity** tab. Select a first batch and **Send unsent** rather than mailing the whole userbase. There is a 500 a day cap, and each row then shows sent, opened, clicked and verified, so you can see who is avoiding it.
5. Filter **Activity** to *Needs action*, read **Flags**, then **Export** and reconcile.

## Next steps

<CardGroup>
  <Card title="Configuration" icon="sliders" href="/docs/verifications/configuration">
    Set what the check does.
  </Card>

  <Card title="Reading Activity" icon="wave-pulse" href="/docs/activity/reading-activity">
    Who took the check, and who came back flagged.
  </Card>

  <Card title="Exporting users" icon="download" href="/docs/activity/exporting-the-list">
    The CSV, and the fields that tie back to your records.
  </Card>

  <Card title="Threat levels and signals" icon="chart-column" href="/docs/insights/threat-levels-and-signals">
    What the bands and families mean.
  </Card>
</CardGroup>


# Branding your check
Source: https://docs.verifyyou.com/docs/verifications/branding-your-check

How to make the check align with your brand.

The **Branding** tab allows you to make the check match your brand. Three controls.

<Frame>
  <img alt="The Branding tab, showing the company name field, the logo upload, and the decline banner toggle under advanced options" />
</Frame>

**Company name** is required. It fills the pre-check modal: "Verifying you for \[name]". Use the name your users already know. If your product name and your legal entity differ, use the product name.

**Logo** is optional. Without one, the check shows a monogram built from the first letter of your company name, so it never looks unfinished.

**Decline banner** sits under advanced options. Turning it on adds an opt-out to the modal and returns a declined event to your product, so somebody who would rather not verify has a way out and you find out they took it.

Changes save from this tab. They can take a few minutes to appear on live and in-progress verifications, so a check somebody is halfway through may still show the old name.

<Note>
  Where people land after the check is set on [Configuration](/docs/verifications/configuration), not here.
</Note>

None of this changes what you receive. Whatever branding a check carries, you get back a verdict, never a face, a name or an image. See [Security and privacy](/docs/how-it-works/security-and-privacy).

**Next:** [Integration](/docs/verifications/integration)


# Configuration
Source: https://docs.verifyyou.com/docs/verifications/configuration

How to make HumanCheck work for your use case.

Configuration allows you to adjust how the check behaves to match your use case. Every verification carries its own, so a strict check before a payout and a light one at signup run at the same time.

Understanding what your check protects is step one to configuring your check to behave how you need it to. For example, a signup that allows one account per human refuses the same human the second time, which you set in **Verification limit** by choosing *Once per lifetime*. A weekly payout cadence may want to allow each person through once per week, which is **Verification limit** on *Once per period* with the period set to weekly.

Our HumanCheck wizard walks you through the whole configuration, and we are here to help you get started on a check for your use case. If you would like a hand, [book a demo](https://sales.verifyyou.com) and we will walk through it with you.

## Identity

<Frame>
  <img alt="Configuration tab, Identity panel with three access types" />
</Frame>

Is the user tied to a credential like an email or phone number, or not?

* **Linked by guest**, the default. Asks for a phone or email, so we know the same person when they switch device
* **Anonymous.** Asks for neither. Recognition stays with the device they used
* **Provided by you.** Takes an identifier from your own system, which the person cannot change. Code path only

Your integration method decides which of the three you can pick, and the tab says so. A check running on a shared link cannot use *Provided by you*, because there is nothing to pass a claim in from. A check that seeds every person from a list you imported can only use *Provided by you*, because the claim is already supplied. Either way the panel offers to switch method.

## Verification limit

How many times should each person be allowed to pass on one verification? It counts successful passes, not attempts.

* **Once per lifetime**, the default. A permanent decision, like opening an account
* **Once per period.** Something recurring, like a weekly payout
* **A few per period.** A set number of passes inside the period you choose, then nothing until it resets
* **Unlimited.** A checkout or a login, where you only need a live human present

<Note>
  Uniqueness covers a whole verification, so once somebody passes, every later run through that check is the same person to us. When one check gates several separate things, your integration sends a **group** to keep them apart. See [start a session](/v3/dev/integrating/start-a-session).
</Note>

## Skip check on known devices

Off by default. Turn it on and somebody returning inside a window you set passes without scanning.

A silent pass still counts as a verification. Skipping changes what the person experiences, not what the check records.

## On collision

<Frame>
  <img alt="The On collision panel, showing Block and Allow + flag, the Maria worked example, when to use each, and the After a denial options" />
</Frame>

What should a second attempt under an alias cost them?

* **Block**, the default. Rejects the duplicate and tells them an account already exists
* **Allow + flag.** Lets them through and raises a flag for your team. Suits shared user pools, where a duplicate is a judgement call

The same panel sets what a denied person can do next, under **After a denial**:

* **No way back**, the default. The denial is final: they see the denied screen and exit
* **Sign in as owner.** The denied screen offers to prove they own the original account. A code goes to the email already on file, shown masked and never typed in, and passing it lets them continue as that identity

## Returning denied people

What happens when a device you already denied comes back.

* **Observe**, the default. Records the retry as a prior-denial flag and lets the fresh check judge them, which keeps the evidence
* **Block at the door.** Stops the device before the check runs. Cheaper, and it also stops the wrong person when a device is shared

## Age gate

Set a minimum estimated age to get through the check. Off by default. The estimate comes from the face scan, with no document to upload, and the thresholds are 13, 16, 18 or 21 and over, or one you set.

<Warning>
  The check returns an estimated age range, not a precise year. Ranges span several years and accuracy is lowest near common thresholds. It is not legally sufficient for regulated products such as alcohol, gambling or firearms. Pair it with proper ID verification for those.
</Warning>

## Redirect URL

Where people are redirected after the check is completed. It sits inside the **Where people land** panel. Left on Default, they see the finish screen with the verdict and a done button. Set a URL and they land there instead.

It saves on its own, straight away. It is not part of the **Save changes** button at the top of the tab.

## Related

<CardGroup>
  <Card title="Start guide" icon="rocket" href="/docs/get-started/getting-access">
    Which of these to answer first.
  </Card>

  <Card title="Gate a signup" icon="door-closed" href="/docs/use-cases/signup-gate">
    A worked job, end to end.
  </Card>

  <Card title="Guests and members" icon="users" href="/docs/how-it-works/guests-and-members">
    What recognition means, and where it stops.
  </Card>

  <Card title="Branding your check" icon="palette" href="/docs/verifications/branding-your-check">
    Set the name and logo people see.
  </Card>
</CardGroup>


# Creating a verification
Source: https://docs.verifyyou.com/docs/verifications/creating-a-verification

Get a verification live in just a few clicks.

Creating a verification is simple, and you can create as many as you like for different use cases on your platform. Each one carries its own settings, so a strict check before a payout and a light one at signup run side by side.

Start from [**New verification**](https://platform.verifyyou.com/dashboard/verifications?new=true) on the Verifications page. Five steps, in this order.

<Frame>
  <img alt="The Verifications page, with the New verification button highlighted top right" />
</Frame>

<Steps>
  <Step title="Get started">
    A short orientation to what you are about to set up. Nothing to fill in, so click through it.
  </Step>

  <Step title="Pick your check">
    Choose a preset: **Signup Gate**, **Account Sweep**, **AI Data Labeling Fraud Audit** or **Build Your Own**. Then choose your integration method, **No-code** for a link you share, or **Code** for the SDK.
  </Step>

  <Step title="Branding">
    Company name, which people see as "Verifying you for \[name]". A logo is optional. See [Branding your check](/docs/verifications/branding-your-check).
  </Step>

  <Step title="Tune your check">
    We make tuning the check for your use case easy with [Configuration](/docs/verifications/configuration), which sets how the check behaves: Can the same human pass twice? Do returning users under a different account get allowed, blocked, or flagged for your team's review? Do you tie each human to an email, phone number, or neither?

    Questions like these all have a simple solution. [Book a demo](https://sales.verifyyou.com) to walk through this with our team.
  </Step>

  <Step title="Integrate">
    No code or code, based on your resource allocation and your use case. No code gets you started with zero developer effort, so you can prove value early without interrupting your roadmap. See [Integration](/docs/verifications/integration).
  </Step>
</Steps>

The preset only sets the starting point. Everything it chose stays editable on the Configuration tab afterwards, and saving there applies to the live check straight away.

## Reuse one you have already tuned

A check you have spent time getting right does not have to be rebuilt to be reused. On the [Verifications page](https://platform.verifyyou.com/dashboard/verifications), open the menu at the end of the check's row and choose **Duplicate**. The setup carries over into a new check under its own label. Adjust what needs adjusting and take it live.

**Next:** [Configuration](/docs/verifications/configuration)


# Integration
Source: https://docs.verifyyou.com/docs/verifications/integration

The four ways to put a check in front of people.

How the check reaches people is your choice, and you can change it whenever you like. Three of the four ways need no developer time at all, so you can prove value early without waiting on your roadmap.

Each verification's **Integration** tab shows the method it is using now, and **Switch method** swaps it.

<Frame>
  <img alt="Switch method dialog listing four integration methods" />
</Frame>

## The three no-code methods

No code gets you started with zero developer effort, so you can prove value early without interrupting your roadmap.

**Sharing a link.** Every verification has its own link in the dashboard. Copy it and put it wherever people already go: the button on your signup page, an invite email, the top of a survey. Somebody who opens it takes the check on our hosted page, and lands wherever you set under Where people land. Nothing to build, and no change to your own code.

**Existing users** (BETA). Import the people you already have, then send each of them a verification request. Paste a list or upload a CSV, and we work out which column holds the email. Everyone you add gets a link locked to their address.

Adding people sends nothing. You send from the verification's **Activity** tab, and we host the sending, so there is no mail system to wire up. Each row then shows sent, opened, clicked and verified.

Sending from your own domain needs DNS records in place first, so plan that in before a large batch. The records to add are in the **Senders** panel on the Activity tab, next to the address your invites leave from.

This is the simplest no code method behind [Userbase healthcheck](/docs/use-cases/userbase-fraud-audit), and [Existing users setup](/docs/guides/existing-users) walks the flow end to end.

**One-time passwords.** A single-use code in front of a survey, form or study, one per person, each good once. [One-time passwords](/docs/guides/pre-generated-passwords) has the setup for four platforms.

## With code

The check runs inside your own product with our SDK, and your server confirms the result before you act on it. Attach your own `external_id` and every result comes back tied to the user record you already keep, which is what makes an export reconcile against your own tables.

Sessions are minted on your server with a secret key, `sk_test_` or `sk_live_`. Test and live are separate partitions and cannot be mixed: a session from one reads as nonexistent under the other, so you can rehearse the whole path before a real person takes it.

Three ways to place it, all through the SDK:

* **Redirect.** We host the whole flow and send the person back to your `redirect_url` with the token on it
* **Drawer.** Slides over your page: a bottom sheet on mobile, a side panel on desktop
* **Inline.** Mounts inside your own element, like an embedded video

Redirect means handling a departure and a return. Drawer and inline resolve on the page they started on.

## Developer documentation

Everything below lives at [docs.verifyyou.com](/v3/dev/integrating/start-a-session), which is the reference your engineers work from.

<CardGroup>
  <Card title="Start a session" icon="play" href="/v3/dev/integrating/start-a-session">
    Mint a session on your server with your secret key, then hand the id to the front end.
  </Card>

  <Card title="Placing your check" icon="window" href="/v3/dev/integrating/placing-your-check">
    Redirect, drawer or inline, with the trade-offs of each.
  </Card>

  <Card title="Handling results" icon="circle-check" href="/v3/dev/integrating/handling-results">
    Confirming server side, and what to gate on.
  </Card>

  <Card title="Server API" icon="server" href="/v3/dev/spec/server-api/initialize">
    Initialize, confirmations, lock, lookup, and return URL parameters.
  </Card>

  <Card title="Browser SDK" icon="code" href="/v3/dev/spec/browser-sdk/vycheck">
    vycheck, vyget, init, VyResult and the error list.
  </Card>

  <Card title="FAQ and changelog" icon="clock-rotate-left" href="/v3/changelog">
    What changed, and the API change policy.
  </Card>
</CardGroup>

## Try it first

**Run a test** on this tab runs the real check on test data, with a test identity you can regenerate. Take it yourself before a real person does.

**Next:** [Reading Activity](/docs/activity/reading-activity)


# Team and roles
Source: https://docs.verifyyou.com/docs/workspace/team-and-roles

Who has access to your workspace.

[**Team**](https://platform.verifyyou.com/dashboard/team) is where your colleagues get access to the workspace.

Invite by email. The member list shows everyone with access, and **Remove** takes somebody off.

Access is per workspace, so anybody you add can see every verification in it, along with the Activity and Insights behind them. There is no per-verification access, which matters if one of your checks gates something the whole team should not be reading.

Our team creates your workspace. You invite your own people once you are in. See the [start guide](/docs/get-started/getting-access).

**Next:** [Guests and members](/docs/how-it-works/guests-and-members)


# VerifyYou Docs
Source: https://docs.verifyyou.com/index

Prove a real, unique, live human on any platform, without the cost, the PII, or the friction of an ID check.

<div>
  <div>
    <div>
      <p>VerifyYou Platform</p>

      <h1>Start verifying with HumanCheck</h1>

      <p>Make trust on your platform simple. Verify that every user is a live, unique human with a selfie check that takes seconds.</p>

      <div>
        <span>
          <Icon icon="magnifying-glass" />
        </span>

        <span>Ask anything about HumanCheck</span>
        <span>⌘K</span>
      </div>

      <div>
        <a href="/v3/dev/integrating/start-a-session"><Icon icon="rocket" />Quickstart</a>
        <a href="/learn/intro-to-verifyyou"><Icon icon="circle-question" />How it works</a>
        <a href="https://app.verifyyou.com/verification/PsvfRgX5SEGeVMB_Prv2Aw"><Icon icon="camera" />HumanCheck Demo</a>
      </div>
    </div>

    <div>
      <svg>
        <path />

        <path />

        <path />
      </svg>
    </div>
  </div>
</div>

<div>
  <h2>Start here</h2>

  <div>
    <a href="/learn/intro-to-verifyyou">
      <span>
        <Icon icon="circle-play" />
      </span>

      <span>
        <Icon icon="circle-play" />
      </span>

      <span>Learn</span>
      <span>What HumanCheck does, in six short modules.</span>
    </a>

    <a href="/docs/get-started/getting-access">
      <span>
        <Icon icon="book-open" />
      </span>

      <span>
        <Icon icon="book-open" />
      </span>

      <span>Docs</span>
      <span>How to set a check up, run it, and read what comes back.</span>
    </a>

    <a href="/v3/dev/integrating/start-a-session">
      <span>
        <Icon icon="code" />
      </span>

      <span>
        <Icon icon="code" />
      </span>

      <span>Developers</span>
      <span>Mint a session, place the check, confirm it on your server.</span>
    </a>
  </div>
</div>

<div>
  <h2>Getting started with VerifyYou</h2>

  <p>Three of the four ways to reach people need no developer time at all.</p>

  <div>
    <div>
      <div>1</div>

      <div>
        <div>Get started</div>

        <div>
          <a href="/docs/get-started/getting-access"><span><Icon icon="rocket" /></span>Start guide</a>
          <a href="/docs/workspace/team-and-roles"><span><Icon icon="users" /></span>Invite your team</a>
          <a href="https://app.verifyyou.com/verification/PsvfRgX5SEGeVMB_Prv2Aw"><span><Icon icon="camera" /></span>Take the check yourself</a>
        </div>
      </div>
    </div>

    <div>
      <div>2</div>

      <div>
        <div>Create a check</div>

        <div>
          <a href="/docs/verifications/creating-a-verification"><span><Icon icon="wand-magic-sparkles" /></span>Creating a verification</a>
          <a href="/docs/verifications/configuration"><span><Icon icon="sliders" /></span>Configuration</a>
          <a href="/docs/verifications/branding-your-check"><span><Icon icon="palette" /></span>Branding</a>
        </div>
      </div>
    </div>

    <div>
      <div>3</div>

      <div>
        <div>Integrate, with or without code</div>

        <div>
          <a href="/docs/verifications/integration"><span><Icon icon="book-open" /></span>Guide</a>
          <a href="/docs/verifications/integration#the-three-no-code-methods"><span><Icon icon="share-nodes" /></span>No code</a>
          <a href="/v3/dev/integrating/start-a-session"><span><Icon icon="code" /></span>With code</a>
        </div>
      </div>
    </div>

    <div>
      <div>4</div>

      <div>
        <div>Read the results</div>

        <div>
          <a href="/docs/activity/reading-activity"><span><Icon icon="wave-pulse" /></span>Reading Activity</a>
          <a href="/docs/activity/guest-profiles"><span><Icon icon="id-card" /></span>Comprehensive trust score</a>
          <a href="/docs/insights/reading-insights"><span><Icon icon="chart-line" /></span>Reading Insights</a>
        </div>
      </div>
    </div>

    <div>
      <div>5</div>

      <div>
        <div>Act on what you find</div>

        <div>
          <a href="/docs/insights/flags"><span><Icon icon="list-check" /></span>Flags</a>
          <a href="/docs/insights/threat-levels-and-signals"><span><Icon icon="chart-column" /></span>Threat levels and signals</a>
          <a href="/docs/activity/exporting-the-list"><span><Icon icon="download" /></span>Exporting users</a>
        </div>
      </div>
    </div>
  </div>
</div>

<div>
  <h2>Find your use case</h2>

  <div>
    <a href="/docs/use-cases/signup-gate">
      <span>
        <Icon icon="door-closed" />
      </span>

      <span>
        <Icon icon="door-closed" />
      </span>

      <span>Gate a signup</span>
      <span>Limit each person to one account.</span>
    </a>

    <a href="/docs/use-cases/gate-key-actions">
      <span>
        <Icon icon="lock" />
      </span>

      <span>
        <Icon icon="lock" />
      </span>

      <span>Gate key actions</span>
      <span>A check on a checkout, a payout or a survey completion.</span>
    </a>

    <a href="/docs/use-cases/userbase-fraud-audit">
      <span>
        <Icon icon="magnifying-glass" />
      </span>

      <span>
        <Icon icon="magnifying-glass" />
      </span>

      <span>Userbase healthcheck</span>
      <span>Sweep the accounts you already have.</span>
    </a>

    <a href="/docs/use-cases/persistent-verification">
      <span>
        <Icon icon="fingerprint" />
      </span>

      <span>
        <Icon icon="fingerprint" />
      </span>

      <span>Persistent verification</span>
      <span>Check the person using the account is the one who opened it.</span>
    </a>
  </div>
</div>

<div>
  <div>
    <h2>See it on your use case</h2>
    <p>Tell us what you are gating and we will set up a workspace and walk you through a live check.</p>

    <div>
      <a href="https://sales.verifyyou.com"><Icon icon="calendar-check" />Book a demo</a>
      <a href="https://app.verifyyou.com/verification/PsvfRgX5SEGeVMB_Prv2Aw"><Icon icon="camera" />HumanCheck Demo</a>
      <a href="/docs/get-started/getting-access"><Icon icon="door-open" />How access works</a>
    </div>
  </div>
</div>


# Create a verification
Source: https://docs.verifyyou.com/learn/create-a-verification



In this module we take you from an empty workspace to a check running inside your product. Our team creates your workspace and sets up the first one with you, and the wizard walks the rest in logical order:

## Match your use case

* Every verification carries its own configuration, so one workspace can run a strict check before a payout and a light one at signup, at the same time
* You decide how many times one person may pass, what happens when the same human comes back, whether an age gate applies, and where people land afterwards. A low-stakes signup and a panel paying for clean data want different answers to all four
* Start from a preset that suits the job. **Signup Gate** runs before an account is created, **Account Sweep** goes back over people who already have accounts, and **Build Your Own** starts from the defaults. [Configuration](/docs/verifications/configuration) has every setting in full

## With or without credentials

* This is the biggest decision. A verified human is recognized by their face plus the device they are on, and switching device breaks that link, so a phone or email re-links the same face on a new one. See [Guests and members](/docs/how-it-works/guests-and-members)
* **Face only** is faster and collects nothing, and recognition stops at that device. It fits one-time verifications where nobody returns
* **Face plus a phone or email** carries recognition wherever they go, which is what most use cases want

## Integration

* **No code** gives you a link to copy and drop into a signup, an email or a survey, and it needs no engineering time at all. See [Integration](/docs/verifications/integration)
* **Code** puts the check inside your own product with our SDK, and your server confirms the result. Attach your own `external_id` and it comes back tied to the user record you already keep. The [quickstart](/v3/dev/integrating/start-a-session) walks that path
* Either way, test keys run the simulator, and the test people it creates stay separate from your live records, so you can scan the QR and take it yourself before a real person does. See [test and live keys](/v3/dev/spec/server-api/authentication)

Not sure which answers fit your platform? [Book a demo](https://sales.verifyyou.com) and we will set the configuration with you, live.

**Next:** [Reading your results](/learn/reading-your-results)


# Intro to VerifyYou
Source: https://docs.verifyyou.com/learn/intro-to-verifyyou



Welcome to VerifyYou! We believe that platforms should have trust at scale without compromising on security, conversion, or cost.

Our HumanCheck [Proof of Human](https://www.ycombinator.com/rfs#proving-youre-human) credential allows platforms to verify a user's humanness and uniqueness, to prevent multi account abuse and AI driven fraud, while maintaining a low friction experience for unproblematic users.

VerifyYou is the culmination of our CTO and co-founder [Marty Weiner](https://www.linkedin.com/in/martyweiner/)'s experience. As Pinterest's founding engineer and [Reddit's former CTO](https://techcrunch.com/2015/08/18/reddit-names-marty-weiner-founding-engineer-at-pinterest-its-first-cto/), he was motivated to build VerifyYou after years of battling bots, spam, and fraud at massive scale. Marty's thesis is that by verifying the human behind the device, fraud becomes economically disincentivized.

AI has made fraud cheaper, easier, and more profitable than ever for bad actors to commit. Current fraud solutions force companies to make an impossible decision, choose passive signals and compromise on security, or choose ID based KYC and sacrifice conversion. HumanCheck is the trust layer between them.

## HumanCheck

We prove a user is human and unique with a simple user experience: Open your phone, and take a selfie.

In the background, we compile over eighty human signals to determine if there's a live person sitting behind the device right now, not an AI injection or presentation attack.

We then convert the user's facial geometry into a numbers-based representation in real time [without storing the raw photo](/docs/how-it-works/security-and-privacy), answering: "Have we seen this user before?" without compromising privacy, to ensure one account per person and recognize a good user coming back.

Device and network fingerprinting, IP and geo, VPN and proxy detection are run in the background to flag high risk signals or inconsistencies which are tied to a human instead of just the device.

## Platform and usage

You can [put HumanCheck wherever works in your flow](/docs/verifications/integration): at signup, before checkout, payment, or prior to key actions to prevent multi account abuse, bot traffic, or as an MFA check to confirm the user logging in is the same user who signed up.

Our dashboard allows you to take action on flagged users, [configure the check how you'd like to block users based on rules you set](/docs/verifications/configuration), or better understand fraud facing your platform by cross referencing your user data, such as location, or credentials such as email and phone number with ours.

We calculate a [comprehensive trust score](/docs/activity/guest-profiles) based on those active and passive signals across every platform using HumanCheck. If we've seen that person [flagged somewhere else in our partner network](/docs/how-it-works/cross-network-recognition), we'll tell you.

**Next:** [VerifyYou platform demo](/learn/platform-demo)


# VerifyYou platform demo
Source: https://docs.verifyyou.com/learn/platform-demo



<div>
  <iframe title="VerifyYou platform demo" />
</div>

In this module we walk you through the VerifyYou platform, from getting started to the value of HumanCheck.

## HumanCheck and the collision

* A check takes seconds: open your phone, and take a selfie. We confirm a live person is there, not a photo or an injected deepfake
* We convert facial geometry into a numbers-based representation and compare it against every check ever run
* When that person returns on a new device behind a VPN, passive signals alone don't connect the attempts, but we still recognize the human. Both accounts are flagged, and with collision block set, the second account never opens

## Shape it to your platform

* A signup gate and a payout gate require different rules, and every verification carries its own, so you can run both at once. See [Create a verification](/learn/create-a-verification)
* Somebody you already verified can come back with no scan at all, while somebody switching phones for a second account is still caught. See [Guests and members](/docs/how-it-works/guests-and-members)
* Put the check inside your own product with our SDK, and your server confirms every result before you act on it. See [Handling results](/v3/dev/integrating/handling-results)

## See what happened, and act on it

* Every check is tied to passive signals, to provide a holistic picture of the user's riskiness. See [Reading your results](/learn/reading-your-results)
* Automate Fraud Prevention by configuring the check to block duplicate accounts or by other rules, or just flag users to audit after the fact. See [Automated Fraud Prevention](/learn/taking-action-on-fraud)
* Export the list to suspend accounts, hold payouts or reconcile against your records, tied to the `external_id` you attached. See [Exporting users](/docs/activity/exporting-the-list)

**Next:** [HumanCheck user experience](/learn/what-your-users-see)


# Reading your results
Source: https://docs.verifyyou.com/learn/reading-your-results



In this module we show you what the dashboard is telling you, from a single check through to the shape of your whole user base.

## Understanding your data

* **Activity** is the record of everyone who completed a verification for your company, most recent first, with the identifier, the trust score, and whether it was approved or denied. Search it by email or phone, and filter to **Needs action** for the ones already worth a look. See [Reading Activity](/docs/activity/reading-activity)
* A denial carries its reason with it, so `limit reached` tells you the verification limit did its job rather than anything being wrong with the person
* **Insights** rolls the same data up across whichever period you pick: **settled passes**, every run that reached a decision; **liveness pass rate**, who proved a live face on capture; and **elevated risk**, how many people scored into the elevated or high bands. See [Reading Insights](/docs/insights/reading-insights)
* **Threat levels over time** stacks your scored sessions by day, and **top threat families** shows what led the score, which tells you whether one person is behind it or many
* Your own systems can ask the same question without anybody opening the dashboard. Send an email or phone to [/v3/confirmations](/v3/dev/spec/server-api/lookup) and you get back where that person stands with you

## Holistic Trust Score

* Click any row and you get that person: signals grouped as **Capture, Person, Location, Device and Network**, with the attributes we estimated and the devices we know them on. See [Comprehensive trust score](/docs/activity/guest-profiles)
* Everyone starts at a spotless 100, and signals collected while they move through the flow deduct from it, so the score tells you how much we saw, while the pass or fail itself is settled by your configuration
* Insights charts the same thing as **threat**, in bands from low to high. A high trust score and a low threat band describe one person, from opposite ends. See [Threat levels and signals](/docs/insights/threat-levels-and-signals)

## Who is arriving, and how

* **Session attributes** shows where sessions come from, with the top five countries, platforms, device types and browsers
* **People** covers who verifies here: liveness passed against failed, an estimated age average and range, and gender
* **Risk flags** gives the share of people arriving with each network or automation flag raised, across VPN, datacenter IP, Tor exit, abuse-listed IP, TLS automation and fingerprint mismatch

**Next:** [Automated Fraud Prevention](/learn/taking-action-on-fraud)


# Automated Fraud Prevention
Source: https://docs.verifyyou.com/learn/taking-action-on-fraud



In this module we show you what to do about the people your checks catch, and most of it happens without you watching.

Three ways to act:

## Decide it once in configuration

* When the same human verifies twice we call that a collision, and your collision setting decides what happens before anyone on your team sees it. **Block** rejects a duplicate and tells them an account already exists, and a new device with a new email does not get round it
* **Allow + flag** lets them through and raises a flag instead, which suits partner sites and shared user pools where a duplicate is a moderation question
* You also decide what happens when a device you already denied comes back: watch it and let the fresh check judge them, or stop it before the check runs. [Configuration](/docs/verifications/configuration) has all of it

## Review what got flagged

* The **Flags** tab shows everyone our system flagged, with the reason attached, scoped to your own traffic and nobody else's. See [Flags](/docs/insights/flags)
* We check for network, geography, accounts, automation and liveness, so a clean tab means every run came through clean
* Filter **Activity** to **Needs action** when you would rather start from whoever the check already thinks deserves attention

## Act in your own product

* **Export** hands you the list, so you can suspend accounts, hold payouts or reconcile against your own records. See [Exporting users](/docs/activity/exporting-the-list)
* Results carry the `external_id` you attached, so you can line a flagged person up against the user you already have. See [Handling results](/v3/dev/integrating/handling-results)
* One person wrongly refused is worth handling directly, and your VerifyYou contact can help. If the same kind of refusal keeps arriving, change the setting rather than handling each person, since a pattern usually means the check is tuned wrong

Fraudsters change tactics, so revisit your limit and your collision action as your traffic changes. [Book a demo](https://sales.verifyyou.com) and we will tune the check with you.

**Next:** [Signup gate](/learn/use-cases/signup-gate)


# Gate key actions
Source: https://docs.verifyyou.com/learn/use-cases/gate-key-actions



You verify somebody once, at signup. The money moves later, and usually more than once. Here's how we put a check on the moment itself with HumanCheck:

1. **The check runs at the action, not at signup.** The account already exists. The check sits in front of the checkout, the payout, the survey completion or the drop, and the action completes once it settles.
2. **People you have already verified are recognized.** Most of them go through without scanning again, so the friction lands on the people you have not seen before.
3. **The limit matches the action.** *Once per lifetime* for something meant to go once per person, *once per period* for a weekly payout, *unlimited* for a checkout where you only need a live human present.
4. **Put it where the incentive is.** A face scan in front of a one dollar survey costs you completes, because there is another survey paying a dollar that does not ask. The same scan in front of the payout does not, because the person is about to be paid and has a reason to finish it.
5. **The outcome is yours to set.** *Block* turns the second attempt away. *Allow + flag* lets it through and records it for your team.

This covers the action. For the account behind it, see [Gate a signup](/docs/use-cases/signup-gate).

## How you start

1. Create a verification for the action. One workspace runs several at once, each with its own settings, so a payout gate can be strict while a checkout stays light.
2. Set **Verification limit** to match the action.
3. Set **On collision** to *Block* where one per person is the rule, or *Allow + flag* where a duplicate is a judgement call.
4. Put it in the flow. Paste the no-code link, or use the SDK and [confirm the result on your server](/v3/dev/integrating/handling-results) before the action completes.
5. Run it on [test keys](/v3/dev/spec/server-api/authentication) first, and watch the completion rate on the first batch before you widen it.

## Next steps

<CardGroup>
  <Card title="One-time passwords" icon="clipboard-list" href="/docs/guides/pre-generated-passwords">
    A worked example, with setup for four survey platforms.
  </Card>

  <Card title="Configuration" icon="sliders" href="/docs/verifications/configuration">
    Set what the check does.
  </Card>

  <Card title="Integration" icon="code" href="/docs/verifications/integration">
    The no-code link, or the SDK.
  </Card>

  <Card title="Guests and members" icon="users" href="/docs/how-it-works/guests-and-members">
    How recognition carries across your checks.
  </Card>
</CardGroup>


# Persistent verification
Source: https://docs.verifyyou.com/learn/use-cases/persistent-verification



Multi-factor proves somebody holds a credential. It cannot tell you they did not hand that credential to somebody else. Here's how we check the same human is still there with HumanCheck:

1. **The first check sets the baseline.** Run one as early as you can, at signup or when somebody completes a profile, and every later check compares against that face.
2. **Every later check asks whether this is the same person.** If it is, they are recognized and pass. If somebody else is holding the account, the run does not tie back to the person who opened it, and the history shows two people where you expected one.
3. **Recognition carries across your checks.** Somebody verified at signup is recognized at payout, so the second check is a few seconds.
4. **You choose the moments.** A payout, a withdrawal, a high value action, or a fixed interval. Each is its own verification with its own settings.
5. **The history sits on the person.** Every confirmation they appear in, newest first, with the devices we know them on and what they have proven. Your server can [ask where somebody stands](/v3/dev/spec/server-api/lookup) by email or phone, without starting a new run.

This tells you whether it is the same person, not who they are. To sweep the accounts you already have once, see [Userbase healthcheck](/docs/use-cases/userbase-fraud-audit).

## How you start

1. Create the baseline verification and put it as early in the account's life as friction allows.
2. Set **Identity** to *Linked by guest*, so a phone or email carries recognition when somebody changes device.
3. Create a second verification for the recurring moment, and set its **Verification limit** to that cadence, for example *once per period*.
4. Turn on **Skip check on known devices** if you would rather people on a device you already know pass without scanning.
5. Read **History** on the person, which lists every confirmation they appear in.

## Next steps

<CardGroup>
  <Card title="Guests and members" icon="users" href="/docs/how-it-works/guests-and-members">
    How recognition carries across devices and checks.
  </Card>

  <Card title="Configuration" icon="sliders" href="/docs/verifications/configuration">
    Every setting on a check.
  </Card>

  <Card title="Comprehensive trust score" icon="id-card" href="/docs/activity/guest-profiles">
    The person view, and the history behind it.
  </Card>

  <Card title="Cross-network recognition" icon="share-nodes" href="/docs/how-it-works/cross-network-recognition">
    Recognition beyond your own workspace.
  </Card>
</CardGroup>


# Gate a signup
Source: https://docs.verifyyou.com/learn/use-cases/signup-gate



There's no limit to how many emails or devices a human can own, but they cannot replace their face. Here's how we limit each person to one account with HumanCheck:

1. **A live person has to be there.** A photo held up to the lens, a recorded video, or a script never gets past this one.
2. **The first account through owns that face.** The scan becomes a face vector, a numerical representation of the face's geometry. Whoever signed up first keeps their account, and nothing here touches them again.
3. **A second signup with that face is recognized as the same person**, whatever email or login they use this time. That holds across your other checks too.
4. **You decide what happens to the second account.** Refuse it, and they are told an account already exists. Or let it through and have the person flagged for your team. The setting is **On collision**.
5. **Ask for a phone or an email.** Set that way, the same person is recognized wherever they sign up from, so a new phone changes nothing. Left anonymous, recognition stays with the device they used, which suits a one-off check and not a signup.

A gate only covers new signups. For the accounts you already have, see [Userbase healthcheck](/docs/use-cases/userbase-fraud-audit).

## How you start

1. Create a verification and pick the **Signup Gate** preset.
2. Set **Identity** to *Linked by guest*, which is the phone or email in point five.
3. Set **Verification limit** to *Once per lifetime*, so one person gets one account, and **On collision** to *Block*.
4. Paste the no-code link into your signup, or use the SDK and [confirm the result on your server](/v3/dev/integrating/handling-results).
5. Run it on [test keys](/v3/dev/spec/server-api/authentication) first. The simulator behaves like the real check, and the test people it creates stay separate from your live records.

## Next steps

<CardGroup>
  <Card title="Configuration" icon="sliders" href="/docs/verifications/configuration">
    Set what the check does, including denials.
  </Card>

  <Card title="Integration" icon="code" href="/docs/verifications/integration">
    The no-code link, or the SDK.
  </Card>

  <Card title="Reading Activity" icon="wave-pulse" href="/docs/activity/reading-activity">
    Who reached the gate, and who was refused.
  </Card>

  <Card title="Guests and members" icon="users" href="/docs/how-it-works/guests-and-members">
    How recognition carries across your checks.
  </Card>
</CardGroup>


# Userbase healthcheck
Source: https://docs.verifyyou.com/learn/use-cases/userbase-fraud-audit



Nothing in your own data proves two accounts are one person. A face does. Here's how we find the duplicates already inside your userbase with HumanCheck:

1. **The check goes to accounts you already have.** Somebody who is who they say they are passes in seconds. Somebody who is not has to explain why they cannot, which your own records were never going to tell you.
2. **Two accounts with one face come back as one person.** Whoever verified first holds that face, and the later account is tied to it, whatever email sits on it.
3. **Everyone who passes leaves a location and a network trail.** VPN, datacenter IP, Tor exit, abuse-listed IP, TLS automation and fingerprint mismatch each land against the person, next to where they verified from, so you can hold it against the country on file.
4. **Flag, do not block.** An audit is not a door. Set the duplicate action to allow and flag, so nobody paying you is locked out while you decide.
5. **You act in your own system.** Export carries the results with the `external_id` you attached, so you can line a flagged person up against the account you already hold.

Run it on the clock you already work to. If payouts go out on a Tuesday, an audit that lands on Wednesday cost you the week. A sweep is a snapshot. To ask the same question at the same moment forever, see [Persistent verification](/docs/use-cases/persistent-verification). For new accounts, see [Gate a signup](/docs/use-cases/signup-gate).

## How you start

1. Create a verification and pick the **Account Sweep** preset.
2. Decide how results tie back to your accounts. **No code**: send to the addresses you already hold and set **Identity** to *Linked by guest*, so the email links that face to that account. **Code**: set it to *Provided by you* and [pass the identifier you already keep](/v3/dev/integrating/start-a-session).
3. Set **On collision** to *Allow + flag*.
4. Send from the verification's **Activity** tab. Select a first batch and **Send unsent** rather than mailing the whole userbase. There is a 500 a day cap, and each row then shows sent, opened, clicked and verified, so you can see who is avoiding it.
5. Filter **Activity** to *Needs action*, read **Flags**, then **Export** and reconcile.

## Next steps

<CardGroup>
  <Card title="Configuration" icon="sliders" href="/docs/verifications/configuration">
    Set what the check does.
  </Card>

  <Card title="Reading Activity" icon="wave-pulse" href="/docs/activity/reading-activity">
    Who took the check, and who came back flagged.
  </Card>

  <Card title="Exporting users" icon="download" href="/docs/activity/exporting-the-list">
    The CSV, and the fields that tie back to your records.
  </Card>

  <Card title="Threat levels and signals" icon="chart-column" href="/docs/insights/threat-levels-and-signals">
    What the bands and families mean.
  </Card>
</CardGroup>


# HumanCheck user experience
Source: https://docs.verifyyou.com/learn/what-your-users-see



<div>
  <iframe title="vimeo-player" />
</div>

In this module we show you what a HumanCheck feels like from the other side, the few seconds your users actually spend with us.

***

## Try it yourself

<Card title="Take the check" icon="camera" href="https://app.verifyyou.com/verification/PsvfRgX5SEGeVMB_Prv2Aw">
  Run it exactly as one of your users would. It works on desktop or mobile.
</Card>

***

What happens at each moment:

## Opening the check

* They arrive from the link you place in your signup, your app, or an email. See [Integration](/docs/verifications/integration)
* The check opens first, before your signup form, your checkout, or whatever you are protecting
* All it needs is a camera, so there is no document to find and nothing to fill in

## The scan

* A few seconds in the camera, with live prompts telling them what to do
* On a desktop it runs there with the webcam, and handing off to a phone by QR code is one optional click. See [Placing your check](/v3/dev/integrating/placing-your-check)
* You receive a verdict and never a photo

## Pass or fail

* Both outcomes are instant
* A pass goes straight through to whatever they came for, with nothing else to do
* A fail is a duplicate face, a replay, or a bot. They do not get through, and a new device or browser changes nothing, because we recognize the face

## When they come back

* On the same check, whether a second attempt is refused is yours to set in [configuration](/docs/verifications/configuration), from unlimited through to once in a lifetime
* On your other checks, we recognize them and you can wave them through with no scan at all
* Someone who comes back and passes without scanning still counts as a verification, since skipping the camera saves them friction rather than saving you verifications

**Next:** [Create a verification](/learn/create-a-verification)


# Product changelog
Source: https://docs.verifyyou.com/product-updates/index

Everything new in HumanCheck: the dashboard and the checks.

Everything new in HumanCheck. Newest first.

<Update label="September 8, 2026" description="Map your import columns yourself, bring in any data you hold, and duplicate a verification">
  Importing arrived last month and worked one thing out for you: which column held the email. This round hands you the rest of the spreadsheet.

  ### Map your columns, and bring whatever data you hold

  Upload a CSV and you now get a **Map columns** step before anything comes in. Three fields sit at the top: **email address**, **IP address**, and **impact figure**. We match them to your columns automatically, and each one is a dropdown, so if we guessed wrong you point it at the right column yourself.

  Only email is required, since it is how we know who a row belongs to. Leave IP or impact unmapped and the import still runs. The gap is noted on screen, those people come in without it, and a later upload can fill it in.

  Everything else in your file imports as extra data on each person's record. Untick a column to skip it this time, or remove it from the list altogether. Each column's type can be set too: currency, date, number, text.

  The step tells you where you stand before you confirm. Rows with no email are skipped and counted, empty cells stay empty rather than being filled in for you, and the summary at the bottom says exactly how many columns are coming in. Long files scroll inside the step with that summary always in view.

  See [Integration](/docs/verifications/integration) and [Userbase healthcheck](/docs/use-cases/userbase-fraud-audit).

  ### Duplicate a verification

  A check you have already tuned no longer has to be rebuilt to be reused. Duplicate it from the dashboard and the setup carries over into a new check under its own label. Adjust what needs adjusting and take it live.
</Update>

<Update label="August 24, 2026" description="Import the users you already have, send each of them a check from the dashboard, and see who verified">
  One theme this month. Checking the accounts you already hold used to mean exporting a list and mailing it yourself. Now you import the list, send from the dashboard, and read the replies in the same place.

  ### Import the people you already have

  **Existing users** is a new way to run a check, and you will find it under **Switch method** on any verification's Integration tab. You bring the list, rather than sharing one link and waiting to see who turns up.

  Paste it in or upload a CSV. Whole spreadsheet rows are fine, with or without a header, because we work out which column holds the email and keep anything else useful on the row. That last part is worth planning for. If you import the IP address you have on file, it comes back beside the one we see when that person verifies, so you can hold your record against ours. Import whatever you would want to compare later, since you cannot add it after the fact.

  Everyone you add gets a verification link locked to their address, so a link that leaks cannot be used by somebody else. Adding people never sends anything, which is deliberate. Sending is its own step.

  It is in beta while we watch how the first sweeps go. See [Integration](/docs/verifications/integration) and [Userbase healthcheck](/docs/use-cases/userbase-fraud-audit).

  ### Send the check, and watch what comes back

  Sending happens on the verification's **Activity** tab, and we host it, so there is no mail system to wire up on your side.

  Write your **Message** once, with the from-address shown next to it. Select the rows you want, or **Select all** on the page, then **Send unsent** goes to everybody you have added who has not been sent to yet. There is a visible daily cap, 500 emails, with a counter above the list so you always know where you are against it.

  Each row then tells you what happened to that person: sent, opened, clicked, verified, with the counts and how long ago. Somebody who opens it three times and never finishes is telling you something, and until now that was invisible.

  ### Send from your own domain

  Your emails can go out from your own domain, so the check arrives from a name your users already recognise. It needs DNS records in place first, so plan that in before a large batch rather than the morning of. Talk to us and we will give you the exact records to add.

  ### Identity, explained where you set it

  The **Identity** setting decides whether a check asks for a phone or email, or asks for neither. It now explains itself on the panel: how identity works, a worked example of each option, and a short list of which jobs suit which. Account creation, e-commerce, surveys and communities sit under one, ticketing and contest entries under another.

  We would still rather walk it with you. See [Configuration](/docs/verifications/configuration), or [book a demo](https://sales.verifyyou.com).

  ### Also new

  * Identity now follows the integration method. On a check running from an imported list, the options that need the person to supply their own email are locked, with the reason on screen and a one-click switch to unlock them.
</Update>

<Update label="July 24, 2026" description="A detailed signal breakdown, filter and export, self-serve branding, and more visibility across your dashboard">
  A big month, mostly pointed at one thing: showing you more of what sits behind every verification, and handing you more control over your checks.

  ### A detailed signal breakdown on every verification

  Our partners told us this visibility changes how their teams handle fraud reviews, so we made it standard for every account. Every verification in your dashboard now carries a complete signal breakdown, so you see the reasoning behind a verdict, not just the verdict itself.

  Click into any check and you'll see the signals grouped into families, each in plain language:

  * **Network.** Where the session is coming from, including VPN, Tor, datacenter, and known-abuser intelligence.
  * **Automation.** How much the session looks like a real browser rather than a script, using TLS fingerprinting.
  * **Velocity.** How fast and how often activity is happening across rolling windows.
  * **Liveness.** Whether a live person was present.
  * **Identity.** Whether this face collides with or contradicts one you have seen before.

  Each family is capped, so no single signal decides a verdict on its own, and together they roll up into a score out of 100 where higher means safer. When a check is blocked, the breakdown tells you exactly why in plain terms: a known abuser on the network, a collision with an existing account, or suspicious velocity. Less guessing, faster reviews.

  See it in [Reading your dashboard](/docs/activity/reading-activity).

  ### Filter and export your verifications

  You can now filter your verifications list by threat level, age, gender, and more, then export exactly what you are looking at as a CSV. It came straight out of a customer request, and it means your team can pull the slice you care about into your own tools without asking us.

  ### Set your own branding

  The branding controls are yours to run now. Set your logo, company name, favicon, and the message a declined user sees, all from the dashboard, without waiting on us. See [Branding your check](/docs/verifications/branding-your-check).

  ### A clear signal when someone drops off

  When a person exits a check partway through, they now land in a trackable "disqualified" state instead of disappearing as unexplained drop-off. For survey and panel teams, that turns a blind spot into a clean, countable completion signal.

  ### Gate a survey with no integration

  Running a study and you don't want to wire anything up? You can now generate a batch of one-time codes in VerifyYou and paste them into your survey platform as a login gate. Each code verifies a real, unique human and works exactly once, so duplicates and professional survey-takers never reach your data. Qualtrics is supported first, with more platforms on the way.

  ### Run the check on desktop or mobile

  Your users no longer have to be on a phone. The check now runs on desktop as well as mobile, so people can complete it right where they are, and a session that starts on one device can carry over to the other with live progress. The SDK embeds directly into your site, wherever your users already are.

  ### Also new

  * A typical integration is down to about four steps.
  * A duplicate at one company no longer blocks that person at another company by default.
  * A full dark mode across the dashboard.
</Update>


# API changes
Source: https://docs.verifyyou.com/v3/change-policy

What we can change without breaking you, what counts as breaking, and how you hear about it.

You are building against a live API. This page says what we can change underneath you, what we cannot, and how you find out.

## The short version

* **`/v3` keeps its shape.** We add to it. We do not remove from it or narrow it.
* **Additive changes ship without notice.** New fields, new optional parameters, new endpoints, new values in a list.
* **Breaking changes get a new version.** `/v3` stays available while you are on it.
* **You hear about breaking changes before they affect you**, by email and in your shared Slack channel if you have one.
* **Everything you can observe lands in the [changelog](/v3/changelog).**

## What we can change without telling you

We make these changes on an ongoing basis, so your integration has to be resilient to them.

| Change                                          | Example                                                                                  |
| ----------------------------------------------- | ---------------------------------------------------------------------------------------- |
| A new field on a response                       | `declined` appearing on a [confirmation](/v3/dev/spec/server-api/confirmations)          |
| A new optional parameter on a request           | `redirect_url` on [`/v3/initialize`](/v3/dev/spec/server-api/initialize)                 |
| A new endpoint                                  | [`POST /v3/confirmations`](/v3/dev/spec/server-api/lookup), the lookup by email or phone |
| A new value in an existing list                 | Another entry in `reasons`                                                               |
| A new error code for a case that already failed | A specific `4xx` where you used to get a generic one                                     |

Two habits cover most of it. Ignore fields you do not recognize, rather than rejecting a response because it grew. Treat `reasons` as an open set and route unknown values to denied, which is what the [confirmations reference](/v3/dev/spec/server-api/confirmations) tells you to do anyway.

If your client rejects unknown fields, a routine additive release will look like an outage on your side.

## What counts as a breaking change

Anything that stops a request you send today from working, or stops a response you read today from parsing. Removing an endpoint, a field, or a parameter. Renaming any of them. Changing the type or format of an existing field. Making an optional parameter required. Dropping a value we used to return.

One more belongs on that list and is easy to miss: changing what a value means while keeping its name. A field that holds its name and its type, and starts meaning something else, is the hardest change to catch from the outside. We call it out in the changelog the same way we call out a removal.

## What our build enforces

We keep the published shape of `/v3` recorded in our source, and our build checks every change against that record. A change that removes an endpoint, a field, or a parameter fails the build. So does one that makes an existing parameter required. Neither can merge.

Editing that record is how we break a version on purpose, and our process is that it only happens when we mint the next version.

The check runs on every pull request to the service behind `/v3`. It is a floor. It does not replace the notice below.

## Versions and deprecation

A breaking change means a new version, served alongside the old one at a new path.

**We do not deprecate a version you are still on.** When `/v4` arrives, `/v3` keeps running. You move when you are ready and tell us once you have. We will ask, and we will tell you what changed and what the move costs you, but the date is yours. A version retires once every integration has left it.

Individual fields and endpoints work the same way inside a version. When something is on its way out we mark it deprecated in the [OpenAPI spec](https://trust.verifyyou.com/openapi.json) and drop it from these pages, and it keeps being served. The spec is where you check whether something you depend on is still first class.

## Pruning what you do not use

Between versions we prune parts of the surface nobody uses in production. If your integration calls an endpoint, that endpoint stays. Where we are unsure, we leave it alone.

Planning to start using something you have not called before? Tell us, and we will treat it as in use from that point.

## How you hear about it

The [changelog](/v3/changelog) carries what changed, what you now see or do, and why it matters. Check it first when something looks different.

**For breaking changes we come to you.** Email is the default, so give us the contacts who need to know. Most teams give us a mix of engineering, product, and whoever carries support, because a change that reaches the people using your product needs to reach somebody who can act on it.

If we share a Slack channel with you, we post there too, and that is usually where the conversation carries on. Email goes out whether anybody is watching that day. Your dashboard carries the same information for your workspace. Treat email as the alert and the changelog as the reference.

We also know when you go live. Once you are running in production we get an alert on our side, and from that point your configuration is part of the compatibility checks we run before a release.

## What we ask of you

1. **Keep your contacts current.** Tell us when the right people change.
2. **Tell us when you go to production**, and when you move between versions.
3. **Confirm on your server.** Exchange the token with [`/v3/confirmations/{token}`](/v3/dev/spec/server-api/confirmations) using your secret key. The `vyc` value on the return URL is a UI hint and the person can edit it.
4. **Pin your SDK version** and upgrade deliberately.

<Note>
  Something changed and you cannot find it in the changelog? Tell us. If you
  spotted it before we published it, that is a miss on our side.
</Note>


# Dev changelog
Source: https://docs.verifyyou.com/v3/changelog

What's new in the VerifyYou SDK, API, and docs.

<Update label="September 9, 2026" description="Skip window">
  ## A new `external_id` is a new check

  If you pass a fresh `external_id` on every session and rely on `group` to keep entries unique, a person coming back inside the skip window could be handed the earlier entry's result: the same confirmation, the earlier `external_id`, and no duplicate reported. A session that carries a different `external_id` than the person's last pass now runs its own check and settles its own confirmation, so a repeat in the same group is reported the way your collision setting says.

  * The same `external_id` coming back still skips, and so does a session with no `external_id`. The skip window itself is unchanged.
  * Nothing to upgrade. It works with the SDK version you already run.
</Update>

<Update label="September 8, 2026" description="Auto-return">
  ## Return the moment a check settles

  [`POST /v3/initialize`](/v3/dev/spec/server-api/initialize) now takes `auto_return`. Set it and an approved check sends the person straight back to `redirect_url` the instant it settles, with no result screen and nothing to tap. Leave it off and they see the result screen and tap to return, as before.

  * Works with any key. It sets the behavior for that one run, whatever the verification has saved.
  * In an embedded flow the result arrives the same way, through the `vycheck()` promise and `onComplete`, and the drawer closes on its own.
  * A denied check still shows its result so the person sees why. Invite links ignore the field.

  Nothing to upgrade. It works with the SDK version you already run.
</Update>

<Update label="August 31, 2026" description="Groups">
  ## One group can now see another

  [Groups](/v3/dev/integrating/start-a-session#groups) scope uniqueness to a pool, and until now every pool was sealed off from the others. [`POST /v3/initialize`](/v3/dev/spec/server-api/initialize) now takes `include_groups`: other groups whose history also counts against the run. To keep everyone who already passed `spring-intake` out of a follow-up, mint the follow-up's sessions with their own `group` plus `include_groups: ["spring-intake"]`.

  * A hit in an included group behaves exactly like one in the run's own pool: it denies the person or flags the pass, following the verification's settings.
  * The confirmation now carries [`groups`](/v3/dev/spec/server-api/confirmations), the pools the `reasons` came from, on flagged passes too. It reads `[]` when there is nothing to report.
  * The run still settles into its own group. An included pool is read, never written.

  Nothing to upgrade. Both fields work with the SDK version you already run, and runs that pass neither field are unchanged.
</Update>

<Update label="August 26, 2026" description="Embedded flow">
  ## Reliability fixes <span>21:30 UTC</span>

  * An older phone scanning the desktop QR code could be told the code was already used on another device. It now resumes where it left off. A different phone opening a used code is still refused.
  * The consent step could do nothing at all for a person whose session had died. It now refreshes and asks for one more tap.
  * Embedded flows now complete inside a native app webview.

  Nothing to upgrade. All three work with the SDK version you already run.

  ## No redirect URL needed for embedded flows <span>16:57 UTC</span>

  Open a verification with [`vycheck({ session, mode: "iframe" })`](/v3/dev/spec/browser-sdk/vycheck) and you no longer have to pass a `redirect_url` to [`POST /v3/initialize`](/v3/dev/spec/server-api/initialize). The embedded flow never leaves your page: when the person finishes, the result arrives through the `vycheck()` promise and your `onComplete` callback, and you [confirm the token](/v3/dev/spec/server-api/confirmations) on your server as before.

  * Applies to the drawer and to `display: "inline"`.
  * A `redirect_url` you do pass still wins, and still comes back with `?vyt=…&vyc=…` appended. If you were only passing one to keep an embed working, you can drop it.
  * Nothing to upgrade. It works with the SDK version you already run.

  Redirect mode is unchanged. It navigates away, so it still needs somewhere to send the person back to.
</Update>

<Update label="July 16, 2026" description="SDK 0.4.0">
  ## Embed a server-minted session

  `vycheck({ session })` runs a session you created on your server, so an embedded flow can carry an `external_id` or a bound identity that only a secret key can set.

  * Call [`POST /v3/initialize`](/v3/dev/spec/server-api/initialize) from your backend with `external_id`, `email`, or `phone`. It now returns a `session_id` next to `url`.
  * Pass the `session_id` to [`vycheck({ session })`](/v3/dev/spec/browser-sdk/vycheck) in the browser. The flow opens as a drawer or inline, with no redirect.
  * Confirm the returned token on your backend as before.

  Embedded flows previously ran from the publishable key alone and couldn't attach an `external_id`. Now they can.

  ## close() on the vycheck handle

  `vycheck()` returns a handle with a `close()` method to dismiss a drawer or inline embed before the person finishes. See [`vycheck()`](/v3/dev/spec/browser-sdk/vycheck).

  ## Documented confirmation reasons

  The [`reasons`](/v3/dev/spec/server-api/confirmations) on a confirmation are now enumerated in the API reference, each with a line on what it means: `collision_company`, `identity_mismatch`, `duplicate_account`, and the rest.
</Update>

<Update label="July 8, 2026" description="SDK 0.2.0">
  ## SDK 0.2.0 is the new default

  `npm install @verifyyou-sdk/client` now installs 0.2.0. The headline: you choose how the flow appears.

  * **Display modes.** Alongside the classic redirect, the flow can now open as a **drawer** that slides over your page or **inline** inside an element you own. Pick the mode once in [`init()`](/v3/dev/spec/browser-sdk/init); `vycheck()` stays the same call.
  * **Completion callbacks.** In the embedded modes the result is delivered to your `onComplete` callback and resolves the `vycheck()` promise. No redirect, no lost page state.
  * **Production by default.** SDK builds now target the production API out of the box.

  If you're on 0.1.1, the core contract is unchanged: the same `vyt`/`vyc` return parameters and the same backend confirmation. See the updated [vycheck()](/v3/dev/spec/browser-sdk/vycheck) and [vyget()](/v3/dev/spec/browser-sdk/vyget) pages for the new result shape.

  ## Richer confirmation responses

  [`GET /v3/confirmations/{token}`](/v3/dev/spec/server-api/confirmations) now returns more than the verdict:

  * `status`: `approved` or `denied` (approved with findings is presented as flagged)
  * `reasons`: the rule findings behind the status, such as `collision_company`
  * `confirmed_at`: when the verdict settled
  * `identity`: the verified email or phone, when your verification has sharing enabled
  * `id`: the confirmation id

  `verified` remains the field to gate on.

  ## Key check endpoint

  `POST /v3/keys/test` validates any key and reports its type and mode. Wire it into setup scripts or healthchecks.

  ## Docs

  * New [`init()`](/v3/dev/spec/browser-sdk/init) page covering setup and the display modes
  * [Identity and recognition](/v3/concepts/identity-and-recognition): clearer story on device IDs and the claim a verified identity gives a person over their own uniqueness
  * Condensed [uniqueness](/v3/concepts/humanness-and-uniqueness) explanation: check group (company or network) and collision action (block or flag)
  * Flow tracking webhooks and the Platform API pages were removed ahead of deprecation
</Update>


# Handling results
Source: https://docs.verifyyou.com/v3/dev/integrating/handling-results

Exchange the token on your server, in the request that performs the action.

Never trust the client result alone. The token (`vyt`) is proof, not a verdict; it exchanges for 30 minutes, secret key only. Do it inside the handler that performs the gated action so the proof and the action never exist apart.

<Tabs>
  <Tab title="With the token">
    ```ts theme={null}
    const VY_SK = process.env.VY_SK;

    const res = await fetch(`https://trust.verifyyou.com/v3/confirmations/${token}`, {
      headers: { Authorization: `Bearer ${VY_SK}` },
    });

    if (!res.ok) {
      // 404 token_invalid  not a token we issued, or not yours; never let them through
      // 410 token_expired  older than the confirmation window; have them run it again
      throw new Error(`verifyyou confirm: ${res.status}`);
    }

    const { verified, status, reasons } = await res.json();

    // use verified for the gate; when it's falsy they failed
    if (!verified) {
      // status is "denied", or "approved" with reasons (flagged)
      // `reasons` says why, e.g. ["collision_company"]
      return { allowed: false, status, reasons };
    }

    return { allowed: true };
    ```
  </Tab>

  <Tab title="Without a token">
    ```ts theme={null}
    const VY_SK = process.env.VY_SK;

    const res = await fetch("https://trust.verifyyou.com/v3/confirmations", {
      method: "POST",
      headers: {
        Authorization: `Bearer ${VY_SK}`,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({ email: user.email }),
    });

    if (res.status === 404) {
      // no_settled_pass: this credential has never finished a run with you
      return { allowed: false, status: "none", reasons: [] };
    }
    if (!res.ok) {
      // 400 one_identifier_only / identifier_unrecognized: send exactly one, well formed
      throw new Error(`verifyyou lookup: ${res.status}`);
    }

    // Same body as the token read. It IS a pass, just the latest one.
    const { verified, status, reasons } = await res.json();
    return { allowed: verified, status, reasons };
    ```
  </Tab>
</Tabs>

<Note>
  The token-free read needs a credential to match on. An **anonymous**
  verification binds none, so it answers `404 no_settled_pass` every time. On
  those checks the `vyt` is your only route to the verdict. See
  [Anonymous checks](/v3/dev/integrating/start-a-session#anonymous-checks).
</Note>

**With the token** is the stronger check: it proves this run just finished, names exactly one pass, and puts no email in your request logs. **Without a token** is a recovery path: it answers whether the email or phone has verified, and lets a returning person skip another redirect. What it cannot tell you is whether they just did a check.

We report `verified: true | false`. Pass or fail is your decision, and routing lives in your code, next to the action.

* Gate on `verified`. `vyc` in the URL is a UI hint.
* Fail closed on `404`, `410`, or a timeout. Fresh session, try again.
* Test keys read test runs only. Never point a live action at a test key.
* Consume each token once. Prefer your own idempotency over [lock](/v3/dev/spec/server-api/lock) unless you mean one pass per human, ever.
* Strip `vyt` and `vyc` from the URL after handoff.

Response fields and reasons: [`GET /v3/confirmations/{token}`](/v3/dev/spec/server-api/confirmations).


# Placing your check
Source: https://docs.verifyyou.com/v3/dev/integrating/placing-your-check

Open the session in the browser with vycheck() and hand the token to your server.

```bash theme={null}
npm install @verifyyou-sdk/client
```

The SDK opens the session your server minted and hands back a token. No key, no `init()`. It is not a router: put `vycheck()` on the action only humans should do, and send the token with that action.

<Warning>
  Drawer and inline mode put the check in an iframe on your page, and that only works from an origin you
  have registered with us. Register yours before you build against them:
  [Register your embedding origin](#register-your-embedding-origin). Redirect mode does not
  require origin registration.
</Warning>

<Tabs>
  <Tab title="Redirect">
    Zero UI to build. We host the whole flow and send them back to `redirect_url` with `?vyt=<token>&vyc=<0|1>`. `vycheck` navigates away, so it never resolves; on the way back, `vyget()` reads the result off the URL.

    ```js 1. where they leave theme={null}
    import { vycheck } from "@verifyyou-sdk/client";

    // `session` is the id provided by your server
    try {
      await vycheck({ session: sessionId });
    } catch (err) {
      // Only reachable BEFORE the browser navigates away: the session expired
      // or was already used, or we couldn't be reached. Mint a new session.
      console.error("verifyyou:", err.message);
      throw err;
    }

    // Nothing below here runs. The page is already gone.
    ```

    ```js 2. where they come back theme={null}
    import { vyget } from "@verifyyou-sdk/client";

    // run on every page load to check for the token (will not error if no token is found)
    const { token } = vyget();

    if (token) {
      // check with your server if the person is verified
      await fetch("/api/verify", {
        method: "POST",
        headers: { "Content-Type": "application/json" },
        body: JSON.stringify({ token }),
      });
    }
    ```
  </Tab>

  <Tab title="Drawer">
    Slides over your page: bottom sheet on mobile, side panel on desktop. No redirect. `vycheck` resolves in place with the result.

    ```js theme={null}
    import { vycheck } from "@verifyyou-sdk/client";

    // `session` is the id from step 1. It runs THAT session, the one already
    // carrying your external_id and redirect_url, so there is no key and no
    // init() on this path.
    try {
      const { token } = await vycheck({ session: sessionId, mode: "iframe" });
      // No token = they closed it without finishing. Not an error; let them retry.
      if (token) {
        // Hand it to your own endpoint; the confirm runs there, with your secret key.
        await fetch("/api/verify", {
          method: "POST",
          headers: { "Content-Type": "application/json" },
          body: JSON.stringify({ token }),
        });
      }
    } catch (err) {
      // Session expired or already used, or we couldn't be reached.
      // Mint a fresh session and let them try again.
      console.error("verifyyou:", err.message);
    }
    ```
  </Tab>

  <Tab title="Inline">
    Mounts inside your own element, like an embedded video. `vycheck` resolves in place with the result.

    ```js theme={null}
    import { vycheck } from "@verifyyou-sdk/client";

    try {
      const { token } = await vycheck({
        session: sessionId,
        mode: "iframe",
        display: "inline",
        container: "#verify-here", // your element; size it with CSS
      });
      if (token) {
        await fetch("/api/verify", {
          method: "POST",
          headers: { "Content-Type": "application/json" },
          body: JSON.stringify({ token }),
        });
      }
    } catch (err) {
      console.error("verifyyou:", err.message);
    }
    ```

    ```html theme={null}
    <!-- the flow fills this element, like an embedded video -->
    <div id="verify-here" style="height: 640px"></div>
    ```
  </Tab>
</Tabs>

## Register your embedding origin

Send us every origin you embed from and we add it to the allowlist. Drawer and inline mode need this.
Redirect mode does not, because it navigates instead of framing.

The page that frames a check can position it, resize it, and draw over it, so that page is part of the
security boundary. We decide which pages are allowed to be it. The permitted origins go in a
[`frame-ancestors`](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Content-Security-Policy/frame-ancestors)
policy on our side and the browser enforces it. Anything not on the list is refused. Nothing you pass from
the browser can widen it, which is what makes it worth having.

Registering is one step per origin, not one per session. Send us the following through
[support](https://verifyyou.com/support):

* Every origin you frame from, across every environment. Production, staging, preview and QA hosts all
  count separately.
* An origin is scheme, host and port with no path and no trailing slash. `https://app.example.com` is an
  origin. `https://app.example.com/` is not.
* Any host on a port other than 443, because `https://app.example.com` covers 443 only.
* Which origins are temporary, so we can take them off again.

If you are not sure which of your hosts to send, open the page where the check appears and read
`window.location.origin` in your browser console. That string is the value, character for character.
Take it from the running page rather than from what a host is called. A host named `api` can still be
the one serving the page that frames the check, and the browser reports the page it loaded, never the
server your own code talks to.

You can ask for a wildcard on your own domain, like `https://*.example.com`, instead of listing hosts. It
covers subdomains only, so add `https://example.com` separately if you frame from the bare domain.

Send us your origins ahead of the launch that needs them. Registration is a change on our side rather
than something that takes effect the moment you ask.

<Note>
  A registered origin is a different thing from your `redirect_url`. Registering one does not register the
  other.
</Note>

## Camera and microphone

The check needs both, and in an iframe your page controls whether it gets them. The SDK sets
`allow="camera; microphone"` on the iframe it creates. A
[`Permissions-Policy`](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Permissions-Policy) header
on your own page still wins over that, so if you send one, delegate both features to
`https://app.verifyyou.com`.

Get this wrong and the flow loads, looks right, then fails at the moment it tries to capture.

Options and modes: [`vycheck()`](/v3/dev/spec/browser-sdk/vycheck). What a rejection looks like: [Errors](/v3/dev/spec/browser-sdk/errors).


# Start a session
Source: https://docs.verifyyou.com/v3/dev/integrating/start-a-session

Mint a session on your server with your secret key.

With your check configured on the dashboard, mint a session for it on your
server and return the `session_id` to your frontend. There is no browser path
to a session; your secret key, and the decision to spend a scan, stay server
side.

```ts theme={null}
const VY_SK = process.env.VY_SK; // sk_test_… while building, sk_live_… to ship

const res = await fetch("https://trust.verifyyou.com/v3/initialize", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${VY_SK}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    verification_id: "<verification_id>",
    // where they land when done
    redirect_url: "http://localhost:3000/verified",
    // optionally set uniqueness to be per group, so the same person can pass once in each group
    // group: "spring-intake",
    // optionally return to redirect_url the moment the check settles, with no result screen
    // auto_return: true,
    // optionally link with your database
    // external_id: user.id,
    // link with a new person or external identifier
    // email: user.email,
  }),
});

if (!res.ok) {
  const { detail } = await res.json();
  // 400 one_identifier_only               send email OR phone, never both
  // 400 identifier_unrecognized           that email/phone isn't a shape we parse
  // 400 invalid_redirect_url              must be absolute, and https off localhost
  // 400 verification_requires_identifier  this check is set to "Provided by you"
  // 401 / 403                             wrong key, or a test-only field on a live key
  // 404 no_matching_verification          that verification_id isn't on your account
  // 409 link_not_active                   this check runs on invites, not on code
  throw new Error(`verifyyou initialize: ${res.status} ${detail}`);
}

// => { session_id: "…", url: "…" }
// use the session_id to run the verification on the frontend;
// a session's ttl is reasonable but not infinite
const { session_id } = await res.json();
```

A session carries at most one identifier, tying the run to whatever you
already use for the account:

| You have            | Send                   | You get back                                                 |
| ------------------- | ---------------------- | ------------------------------------------------------------ |
| An existing account | `external_id`          | Duplicates reported against your id                          |
| A new signup        | `email` or `phone`     | The run is bound to that identity; the person cannot swap it |
| Nothing (anonymous) | just `verification_id` | A session, and a pass with no identity attached to it        |

## Groups

Uniqueness covers the whole verification: once someone passes, every later run
through that check reads as the same person, and a repeat attempt reports as a
duplicate. Sometimes that is too broad. If one check gates several distinct
things, separate surveys or product drops for instance, send a `group` to
scope uniqueness to each one. The same person can then pass once in
`spring-intake` and once in `fall-intake`, but never twice in either.

Sometimes one pool needs to see another. To keep everyone who already passed
`spring-intake` out of a follow-up, mint the follow-up's sessions with its own
`group` plus `include_groups: ["spring-intake"]`. History in an included group
counts against the run exactly as its own would: whether a hit denies the
person or only flags the pass follows the verification's settings, and the
confirmation's `groups` field names the pools the hit came from. The run still
settles into its own group. An included pool is read, never written.

## Anonymous checks

A verification configured as **Anonymous** sends people straight to the check,
with no identifier step. It fits flows where nobody returns, and it carries
trade offs:

* After a person's token expires, you have no identifier to look them up by.
* Reusing the verification requires a [group](#groups). Without one, any
  repeat attempt through it is blocked.

Anonymous does not mean client side. The session is still minted on your
server, for two reasons: a browser alone cannot flood your account with
scans, and you choose when a check runs at all, so a request your own signals
flag as low quality never spends one. A scan is spent deliberately.

<Warning>
  Even with no identifier on the run, an anonymous verification meters
  **one successful pass per person, for life**. If your second test run comes back
  denied, this is why. Send a [`group`](#groups) to reuse the verification, and
  the pass counts once per group instead.
</Warning>

For full parameters and errors: [`POST /v3/initialize`](/v3/dev/spec/server-api/initialize).


# Errors
Source: https://docs.verifyyou.com/v3/dev/spec/browser-sdk/errors

What vycheck() rejects with, and how to handle it.

`vycheck()` never throws synchronously. Failures arrive as a promise rejection, and every rejection today is a plain `Error`: read `err.message`, not a code.

```js theme={null}
try {
  const { token } = await vycheck({ session: sessionId, mode: "iframe" });
  if (!token) {
    // They closed it without finishing. Not an error. Let them retry.
  }
} catch (err) {
  // Session expired or already used, or the network failed. Mint a fresh
  // session and let them try again.
  console.error("verifyyou:", err.message);
}
```

The common failure is opening the session: a non-2xx rejects with `VerifyYou: initialize failed (HTTP <status>)`. The session expired or was already used; mint a fresh one.

## Dismissal is not an error

Closing a drawer or inline embed without finishing **resolves** with `{ token: null, verified: false, vyc: null }`. Check for a missing `token`; do not rely on `catch`.

## An unregistered origin is not a rejection either

Call `vycheck({ session, mode: "iframe" })` from an origin we have not allowlisted and the browser refuses the frame
before any of our code runs. There is nothing to reject. The iframe stays blank, the promise never settles,
and `catch` never fires.

You will see a browser message in the frame saying `app.verifyyou.com` refused to connect, and a
`frame-ancestors` violation in the console. That is a setup step you have not done yet, not a fault in your
code. See [Register your embedding origin](/v3/dev/integrating/placing-your-check#register-your-embedding-origin).

## Redirect mode never rejects after navigation

In redirect mode `vycheck()` navigates the page away, so its promise never settles and nothing after it runs. Error handling for that path belongs on the return page, around `vyget()` and your own confirmation call.

## VerifyYouError

The package exports a typed error class for transport failures. **No code path throws it today**, so do not branch on `instanceof VerifyYouError`. It exists for forward compatibility; when it does fire, it is still an `Error`, so `err.message` handling keeps working.

```ts theme={null}
class VerifyYouError extends Error {
  code: "timeout" | "network" | "http" | "bad_response";
  status?: number; // when code === "http"
}
```

It is not on the CDN global; the IIFE build exposes only `init`, `vycheck`, and `vyget`.


# init()
Source: https://docs.verifyyou.com/v3/dev/spec/browser-sdk/init

Optional. Set vycheck() defaults once.

## Signature

```ts theme={null}
function init(config: InitConfig): void;
```

Optional. Anything here can be passed to [`vycheck()`](/v3/dev/spec/browser-sdk/vycheck) per call instead; use `init()` to set it once.

## Options

Presentation and callbacks: `mode`, `display`, `container`, `inlineHeight`, `theme`, `onComplete`, `onClose`. Same meaning as on [`vycheck()`](/v3/dev/spec/browser-sdk/vycheck#options).

Deprecated and still accepted: `publishableKey`, `email`, `phone`, `config`, `origin`, `returnPath`. All belong to browser-started runs; mint the session on your server instead.


# vycheck()
Source: https://docs.verifyyou.com/v3/dev/spec/browser-sdk/vycheck

Open a session and get a handle that resolves with the result.

```bash theme={null}
npm install @verifyyou-sdk/client
```

```ts theme={null}
import { vycheck, vyget, init, VerifyYouError } from "@verifyyou-sdk/client";
import type { VyCheckOptions, VyCheckHandle, VyResult, InitConfig } from "@verifyyou-sdk/client";
```

## Signature

```ts theme={null}
function vycheck(options: VyCheckOptions): VyCheckHandle;

type VyCheckOptions = Partial<InitConfig> & { session: string };

interface VyCheckHandle extends Promise<VyResult> {
  close(): void; // dismiss an embed early; no-op in redirect mode or once settled
}
```

## Options

<ParamField type="string">The `session_id` from `/v3/initialize`. The SDK opens that run: no key, no `init()`.</ParamField>
<ParamField type="&#x22;redirect&#x22; | &#x22;iframe&#x22;">`redirect` navigates to the hosted flow and back. `iframe` embeds it.</ParamField>
<ParamField type="&#x22;drawer&#x22; | &#x22;inline&#x22;">Iframe only. Drawer overlays the page; inline mounts into `container`.</ParamField>
<ParamField type="HTMLElement | string">Inline only. Element or CSS selector.</ParamField>
<ParamField type="&#x22;fill&#x22; | &#x22;auto&#x22; | string">Inline only. Or a CSS length like `640px`.</ParamField>
<ParamField type="&#x22;light&#x22; | &#x22;dark&#x22; | &#x22;auto&#x22;">Iframe only.</ParamField>
<ParamField type="(result: VyResult) => void">Iframe only. Same result as the promise.</ParamField>
<ParamField type="() => void">Iframe only. The person dismissed without finishing.</ParamField>

Any of these can be set once with [`init()`](/v3/dev/spec/browser-sdk/init) instead.

<Note>
  `iframe` works only from an origin registered with us. From any other origin the browser refuses the
  frame and the promise never settles. See
  [Register your embedding origin](/v3/dev/integrating/placing-your-check#register-your-embedding-origin).
</Note>

## Returns

| Mode       | Behavior                                                                            | Promise                                                                                                                                                                |
| ---------- | ----------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `redirect` | Navigates to the hosted flow. The person returns to `redirect_url` with `?vyt&vyc`. | Never resolves. Read the result with [`vyget()`](/v3/dev/spec/browser-sdk/vyget).                                                                                      |
| `iframe`   | Mounts as drawer or inline.                                                         | Resolves with [`VyResult`](/v3/dev/spec/browser-sdk/vyresult); `onComplete` fires. Dismiss resolves `{ token: null, verified: false, vyc: null }` and fires `onClose`. |

## Errors

Rejects when opening the session fails, with an ordinary `Error` today; read `err.message`. Never throws synchronously. Dismiss is not an error. See [Errors](/v3/dev/spec/browser-sdk/errors).

## Example

```ts theme={null}
const handle = vycheck({ session, mode: "iframe", display: "inline", container: "#verify-here" });
cancel.onclick = () => handle.close();
const { token } = await handle;
```


# vyget()
Source: https://docs.verifyyou.com/v3/dev/spec/browser-sdk/vyget

Read the result off the return URL, or the last embedded completion.

## Signature

```ts theme={null}
function vyget(): VyResult;
```

Synchronous, no network. Checks the URL for `vyt`/`vyc` first, then the last iframe completion on this page. Safe on every page load.

## Returns

| Situation                   | [`VyResult`](/v3/dev/spec/browser-sdk/vyresult) |
| --------------------------- | ----------------------------------------------- |
| `?vyt=tok&vyc=1`            | `{ token: "tok", verified: true, vyc: "1" }`    |
| `?vyc=0`                    | `{ token: null, verified: false, vyc: "0" }`    |
| Embedded run just completed | That result                                     |
| Nothing                     | `{ token: null, verified: false, vyc: null }`   |

Strip `vyt` and `vyc` with `history.replaceState` after handoff. Full list of reserved params: [Return URL parameters](/v3/dev/spec/server-api/return-url).


# VyResult
Source: https://docs.verifyyou.com/v3/dev/spec/browser-sdk/vyresult

The result shape.

```ts theme={null}
interface VyResult {
  token: string | null;  // vyt; send to your server
  verified: boolean;     // vyc === "1"; UI hint only
  vyc: string | null;    // "1" | "0" | null
}
```

`token` is the only field your server needs. `verified` and `vyc` are what the browser saw; never gate on them.


# Authentication
Source: https://docs.verifyyou.com/v3/dev/spec/server-api/authentication

Base URL, keys, partitions, and the errors every endpoint can return.

Base URL `https://trust.verifyyou.com`. `Authorization: Bearer <secret key>` on every request. Raw spec: [`openapi.json`](https://trust.verifyyou.com/openapi.json). Try it: [Swagger UI](https://trust.verifyyou.com/docs).

| Endpoint                                                                              | Purpose                             |
| ------------------------------------------------------------------------------------- | ----------------------------------- |
| [`POST /v3/initialize`](/v3/dev/spec/server-api/initialize)                           | Mint a session                      |
| [`GET /v3/confirmations/{token}`](/v3/dev/spec/server-api/confirmations)              | Exchange a token for the verdict    |
| [`POST /v3/confirmations/{token}/lock`](/v3/dev/spec/server-api/lock)                 | Consume a pass                      |
| [`POST /v3/confirmations`](/v3/dev/spec/server-api/lookup)                            | Verdict by email or phone, no token |
| [`POST /v3/test/confirmation-token`](/v3/dev/spec/server-api/test-confirmation-token) | Mint a token for your test suite    |

## Keys

Secret keys, `sk_test_…` and `sk_live_…`. Server only. Test keys see test runs; live keys see live runs. A token or session from one partition reads as nonexistent under the other.

Publishable keys (`pk_*`) are deprecated. Start every session server side and open it in the browser with `vycheck({ session })`.

## Errors on every endpoint

Errors are `{ "detail": "<code>" }`, except `422` (schema validation, an array).

| Status | `detail`                  | When                       |
| ------ | ------------------------- | -------------------------- |
| `401`  | `authentication_required` | No `Authorization` header. |
| `401`  | `invalid_key_type`        | Not a secret key.          |
| `401`  | `invalid_or_revoked_key`  | Key not found or revoked.  |

Deprecated and still served (see the [OpenAPI spec](https://trust.verifyyou.com/openapi.json)): `POST /v3/keys/test`.


# Server-side clients
Source: https://docs.verifyyou.com/v3/dev/spec/server-api/clients

Generated clients, or bring your own generator.

Java, TypeScript, C#, and Python clients generated from the spec: [`verifyyou-sdks`](https://github.com/VerifyYou/verifyyou-sdks).

```bash theme={null}
npx @hey-api/openapi-ts -i https://trust.verifyyou.com/openapi.json -o src/verifyyou
```


# /v3/confirmations/{token}
Source: https://docs.verifyyou.com/v3/dev/spec/server-api/confirmations

Exchange a vyt token for the authoritative verdict.

`GET` Secret key. Tokens exchange for 30 minutes. A token from another company or the other test/live partition reads as nonexistent.

## Path parameter

<ParamField type="string">The `vyt` from the return URL or the SDK result.</ParamField>

## Response

<ResponseField name="verified" type="boolean">Gate on this. `true` only when approved and not locked.</ResponseField>
<ResponseField name="status" type="&#x22;approved&#x22; | &#x22;denied&#x22;">Approved with `reasons` is "flagged".</ResponseField>
<ResponseField name="reasons" type="string[]">`collision_company`, `identity_mismatch`, `external_identity_mismatch`, `duplicate_account`, `linked_denial`, `limit_reached`, `face_self_mismatch`, `age_blocked`, `guest_declined`, `no_invite`. Open set; route unknown values to denied.</ResponseField>
<ResponseField name="declined" type="boolean">The person chose not to scan. Denied, but not failed.</ResponseField>
<ResponseField name="group" type="string | null">The pool the run was judged in, when `initialize` was called with a [`group`](/v3/dev/integrating/start-a-session#groups). `null` otherwise.</ResponseField>
<ResponseField name="groups" type="string[]">Where the `reasons` came from: the pools whose earlier passes produced them, the run's own `group` or one it [included](/v3/dev/integrating/start-a-session#groups). Populated on flagged passes too. Empty when nothing hit.</ResponseField>

```json theme={null}
{ "verified": true, "status": "approved", "reasons": [], "declined": false, "group": null, "groups": [] }
```

## Errors

| Status | `detail`        | When                                                       |
| ------ | --------------- | ---------------------------------------------------------- |
| `404`  | `token_invalid` | Not ours, not yours, wrong partition, or the pass is gone. |
| `410`  | `token_expired` | Older than 30 minutes. Run it again.                       |

Denied, declined, and locked are `200` with `verified: false`.

Deprecated and still returned (see the [OpenAPI spec](https://trust.verifyyou.com/openapi.json)): `id`, `confirmed_at`, `locked`, `is_test`, `score`, `band`, `external_id`, `identity`.


# /v3/initialize
Source: https://docs.verifyyou.com/v3/dev/spec/server-api/initialize

Mint a session and get back session_id and the hosted URL.

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

## Body

<ParamField type="string (uuid)">Which verification to run. Omit for your default.</ParamField>
<ParamField type="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.</ParamField>
<ParamField type="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.</ParamField>
<ParamField type="string">Bind the run to this email. The flow cannot collect a different one. One of `email` or `phone`.</ParamField>
<ParamField type="string">Bind the run to this phone. Same rules.</ParamField>
<ParamField type="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](/v3/dev/integrating/start-a-session#groups).</ParamField>
<ParamField type="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](/v3/dev/integrating/start-a-session#groups).</ParamField>
<ParamField type="object<string, string>">Extra query params echoed onto the return URL. `vy*` names are ignored.</ParamField>
<ParamField type="object">Test key only. Per-run config override, used verbatim, never merged.</ParamField>
<ParamField type="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.</ParamField>

## Response

<ResponseField name="session_id" type="string">Open it with `vycheck({ session })`.</ResponseField>
<ResponseField name="url" type="string">Hosted link with the run queued up.</ResponseField>

```json theme={null}
{ "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

```bash theme={null}
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](https://trust.verifyyou.com/openapi.json)): `verification_external_id`, `external_tracker`, `expire_in_days`, and the `invite_id` response field.


# /v3/confirmations/{token}/lock
Source: https://docs.verifyyou.com/v3/dev/spec/server-api/lock

Consume a pass so it reads as not passed everywhere.

`POST` Secret key. Idempotent. Applies to the person's pass on this verification, not just the token.

Use it for one pass per human, ever. For double-submit protection use your own idempotency on the token. For once-per-period caps configure a limit on the verification.

## Path parameter

<ParamField type="string">The `vyt` for the pass to lock.</ParamField>

## Response

Same shape as [`GET /v3/confirmations/{token}`](/v3/dev/spec/server-api/confirmations); after locking, `verified` is `false`.

## Errors

| Status | `detail`        | When                                                       |
| ------ | --------------- | ---------------------------------------------------------- |
| `404`  | `token_invalid` | Not ours, not yours, wrong partition, or the pass is gone. |
| `410`  | `token_expired` | Older than 30 minutes.                                     |


# /v3/confirmations
Source: https://docs.verifyyou.com/v3/dev/spec/server-api/lookup

Latest settled pass by email or phone, no token.

`POST` Secret key. Scoped to your company and partition. Weaker than the token exchange: it says where the person stands, not that a run just finished.

## Body

<ParamField type="string">As sent to `initialize`. Exactly one of `email` or `phone`.</ParamField>
<ParamField type="string">Alternative.</ParamField>
<ParamField type="string (uuid)">Narrow to one verification. Omit for all of yours.</ParamField>
<ParamField type="string">Narrow to one group, so you read where the person stands in that pool. Omit to read across every group, passes carrying none included.</ParamField>

## Response

Same shape as [`GET /v3/confirmations/{token}`](/v3/dev/spec/server-api/confirmations).

## Errors

| Status | `detail`                  | When                           |
| ------ | ------------------------- | ------------------------------ |
| `400`  | `one_identifier_only`     | Both or neither.               |
| `400`  | `identifier_unrecognized` | Not parseable.                 |
| `404`  | `no_settled_pass`         | Never finished a run with you. |


# Return URL parameters
Source: https://docs.verifyyou.com/v3/dev/spec/server-api/return-url

What is appended to redirect_url.

| Param              | Meaning                                                     |
| ------------------ | ----------------------------------------------------------- |
| `vyt`              | Confirmation token. Exchange server side within 30 minutes. |
| `vyc`              | `1` passed, `0` not. UI hint. Never gate on it.             |
| your `pass_params` | Echoed as sent.                                             |

Every name starting with `vy` is reserved. Strip `vyt` and `vyc` after handoff.


# /v3/test/confirmation-token
Source: https://docs.verifyyou.com/v3/dev/spec/server-api/test-confirmation-token

Mint a real test vyt with the verdict you choose.

`POST` Test secret key only. Settles a real pass in your test partition and returns its token. Use it to drive every branch of your result handling from a test suite.

## Body

<ParamField type="&#x22;approved&#x22; | &#x22;denied&#x22;">Verdict to settle with.</ParamField>
<ParamField type="string[]">Reasons to attach. Unknown values are rejected.</ParamField>
<ParamField type="string (uuid)">Default when omitted.</ParamField>

## Response

<ResponseField name="token" type="string">Exchange at `GET /v3/confirmations/{token}` with the same test key.</ResponseField>
<ResponseField name="verified" type="boolean">What the exchange will report.</ResponseField>

## Errors

| Status | `detail`                                          | When                 |
| ------ | ------------------------------------------------- | -------------------- |
| `403`  | `test_key_required`                               | Live key.            |
| `400`  | `{ "error": "unknown_reason", "reasons": [...] }` | Unknown reason.      |
| `404`  | `no_matching_verification`                        | Not on your account. |


# FAQ
Source: https://docs.verifyyou.com/v3/faq

Common questions about verifying, keys, returning people, and data.

<AccordionGroup>
  <Accordion title="What does “verified” actually mean?">
    That the person passed two checks: they're a **live human** (a face check,
    not a photo, video, mask, or generated face) and they're **unique** (their
    face doesn't match someone else who already verified in the
    [scope that applies](/v3/concepts/humanness-and-uniqueness): your company,
    or one group inside it). A confirmation returns `verified: true` only when
    both pass.
  </Accordion>

  <Accordion title="Can I trust the ?vyc value on the return URL?">
    No. Treat it as a UI hint only. Anyone can edit a URL. Always send the
    `vyt` token to your backend and
    [confirm it](/v3/dev/spec/server-api/confirmations) with your secret key. That result is
    authoritative.
  </Accordion>

  <Accordion title="Which key do I use where?">
    The **secret key** (`sk_…`) stays on your server. It mints sessions at
    initialize and confirms tokens. The browser needs no key at all: it opens
    the session your server minted with `vycheck({ session })`. Publishable
    keys (`pk_…`) are deprecated. Never ship a secret key to the client.
  </Accordion>

  <Accordion title="How do test and live modes work?">
    Each key comes in a test and a live flavor (`sk_test_…` / `sk_live_…`).
    Test keys run the simulator and create test people, isolated from live
    records. Build against them freely. Switch to the live key to verify real
    people.
  </Accordion>

  <Accordion title="Why did a returning person get blocked?">
    Most often it's an **anonymous person** whose device ID is gone: they
    cleared the browser, switched devices, or used a private window. They look
    new, but their face is still on record, so they collide with their own
    earlier verification. Bind repeat visitors to a
    [verified phone or email](/v3/concepts/identity-and-recognition) so they
    can be recognized and re-linked instead of blocked.
  </Accordion>

  <Accordion title="Does a person have to verify every time?">
    No. Within your verification's skip window, someone who already passed
    completes almost instantly. A person with a **bound identity** is also
    recognized on new devices: their face is matched and they sign back in
    with their number or email to re-assert their claim. An anonymous person
    is recognized only by the device ID in their browser, so they re-verify
    more often. See [Returning people](/v3/concepts/returning-users).
  </Accordion>

  <Accordion title="What if the person is on a desktop?">
    The flow runs in place with their webcam. If they'd rather use their phone,
    one click shows a QR code that moves the same session to their phone's
    browser, and the desktop follows along in realtime and returns to your site
    automatically when they finish. See
    [Humanness and uniqueness](/v3/concepts/humanness-and-uniqueness#any-device-including-desktop).
  </Accordion>

  <Accordion title="How do I tie a verification to my own account records?">
    Pass `external_id` (and optionally `phone`/`email`) at
    [initialize](/v3/dev/spec/server-api/initialize) from your server.
    Duplicates are reported against your id. See
    [Account linking](/v3/advanced/account-linking).
  </Accordion>

  <Accordion title="I have a one-time form and don't want resubmissions. What do I use?">
    Usually **not** lock. Use your own idempotency on the submission so the same
    token is not accepted twice. That stops a resubmission without affecting the
    person's ability to verify again later. For caps like once per week or once per
    event, set a verification limit in the dashboard.

    Reach for
    [locking](/v3/dev/spec/server-api/lock) only when you mean
    **one pass per person, ever**. Locking applies to the person's confirmation, not
    just the token in your hand: their future passes on this verification come back
    denied too, and **there is no unlock**. After locking,
    `GET /v3/confirmations/{token}` returns `verified: false`.
  </Accordion>
</AccordionGroup>