Skip to main content

​
What to expect when testing

If you’re running the full flow yourself in a browser — not just hitting the API — there are a few things to know up front.

​
Heads up if you’re testing on desktop

If you open the verification URL on a laptop or desktop, you’ll be handed off to your phone via a QR code — the liveness capture only runs on mobile. Scan the QR, finish the flow on your phone, and the desktop tab will advance and redirect back on its own. See the Quick start for the full breakdown.

​
Test phone numbers are required

In sandbox mode, you must use a test phone numbers via the sandbox API. You can generate a number and its verification code first via POST /v2/sandbox/phone-number, then enter both when the flow prompts you.

​
Account state persists beyond your browser

VerifyYou tracks accounts at the user level, not the browser level. Your verified phone number acts as a persistent identifier that follows the account across devices and sessions — clearing cookies, switching devices, or opening an incognito window won’t give you a fresh start. When you’re testing, you’ll probably run into this pretty quickly — and from the API side it can feel like a bug. You’ll call verification.create, push the same user (or someone close) through the flow a second time, and not get the fresh slate you expected. That’s by design: every verification you create is tied to a user at creation time, and that tie follows them through the whole lifecycle on our end. Incognito, cleared cookies, a different browser, a new device — none of that gives you a fresh start, because the state lives on our servers, not in your browser. One verified account per user per company is the rule. To keep testing, you’ve got two options: delete the account (see below) and re-run the same user, or kick off a new verification.create with a different test phone number so you’re binding a different user. If something looks genuinely broken (not just “I got blocked again”), report it to us — we want to know. If you actually need a clean slate (which is often when testing), visit /del on the VerifyYou web app to delete your account, then try again.

​
Landing in human review

On your second attempt through the flow, you’ll should land in human review. The reason is simple: your face is already on file from the first run, so the second attempt collides with an existing verified account — and that collision is what sends you to human review. Human review is a safety net, not a catch-all — in production it should see very little traffic. You won’t see a big scary error when you land here; things just sort themselves out in the background.
The human review step can be annoying during development. We’re working on a sandbox dashboard where you can self-approve pending verifications for testing — no ETA yet, but reach out if it’s slowing you down.

​
Sandbox API

The sandbox endpoints let you test the full verification flow without real phone numbers or SMS. No API key is needed — unauthenticated access works out of the box.
Public access to these endpoints is heavily rate limited. Please use an API key when possible.

​
Generate a test phone number

Call POST /v2/sandbox/phone-number to get a random test phone number and its verification code in one shot. 
const response = await fetch("https://api.connect.verifyyou.com/v2/sandbox/phone-number", {
  method: "POST",
});

const data = await response.json();
const phone = data.phone_number;       // "+999011234567"
const code = data.verification_code;   // "234567"
Response
{
  "phone_number": "+999011234567",
  "verification_code": "234567"
}
You can request US-formatted numbers by passing type and area_code: 
const response = await fetch("https://api.connect.verifyyou.com/v2/sandbox/phone-number", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({ type: "us", area_code: "415" }),
});
Response
{
  "phone_number": "+14155550142",
  "verification_code": "550142"
}

​
Look up a verification code

Already have a test phone number? Call POST /v2/sandbox/verification-code to get its code. 
const response = await fetch("https://api.connect.verifyyou.com/v2/sandbox/verification-code", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({ phone_number: "+14155550142" }),
});

const code = (await response.json()).verification_code;  // "550142"
Response
{
  "verification_code": "550142"
}
The verification code is always the last 6 digits of the phone number. Only test phone numbers are accepted — real numbers will return a 400 error.

​
Test phone number ranges

Test numbers use reserved ranges that never send real SMS and never trigger real verifications:
RangeFormatExample
Global (ITU E.164 test range)+99901 followed by 7-12 digits+999011234567
US (NANP 555 block)+1{area_code}555-01xx+14155550142

​
Full test flow

Here’s how to run the complete verification cycle end-to-end. The loop is: generate a test phone number → create a verification → complete the human step in a browser → check status → delete the account and repeat if you want another clean run.
The liveness + uniqueness scan has to be completed in a browser by a real human in front of a camera. It’s intentionally not API-automatable — don’t try to wire it into an automated test suite. The script below handles the backend steps; the human step happens in the hosted flow.
1. Backend steps (scriptable):
Python
import requests

# 1. Generate a test phone number
sandbox = requests.post(
    "https://api.connect.verifyyou.com/v2/sandbox/phone-number",
).json()
print(sandbox)
# {"phone_number": "+999011234567", "verification_code": "234567"}

# 2. Create a verification
verification = requests.post(
    "https://api.connect.verifyyou.com/v2/verification/create",
    json={"redirect": "https://yourapp.com/verified"},
).json()
print(verification)
# {"verification_url": "https://verifyyou.com/i/A3KF9X", "external_id": "d4f8e2a1-..."}
2. Human step (browser, manual): open verification_url in a browser, enter the sandbox phone number and its verification code, then complete the liveness capture in front of a camera. 3. Check the status (scriptable):
Python
# After the human has finished the flow in the browser
status = requests.post(
    "https://api.connect.verifyyou.com/v2/verification/status",
    json={"external_id": verification["external_id"]},
).json()
print(status)
# {"verification_complete": true, "external_id": "d4f8e2a1-..."}
4. Restart the loop (for repeat testing, spoof attempts, etc.): Once you’ve verified, your face is on file — the next run through the flow will collide with your existing account and land in human review (see Landing in human review). To get a clean slate, visit /del on the VerifyYou web app to delete your account, then start again from step 1.