Skip to content
IDVERF

Docs · Sandbox

Sandbox & testing

Build and test your whole integration for free. Sandbox keys work like live keys: same base URL, same endpoints, same response shapes. The difference is that identity and contact results come from fixed magic values, so you can get any decision when you want it.

Test keys

Free

sk_test_ calls are never billed and don't need a balance.

No live data

Test keys never call live data sources. Use made-up people, not real customer data.

No real texts

Phone codes and session link emails are simulated. Nothing is texted or emailed. The test code is 000000.

Real document logic

Document checks (barcode, MRZ, number format, dates) use our real logic, so test with realistic document data.

Create test keys in the portal under Developers → API keys. Call https://api.idverf.com/v1 (or https://sandbox.api.idverf.com/v1) with them. Responses include "livemode": false. Test verifications, policies and webhooks are kept apart from live ones. Your account's access rules still apply in the sandbox, so you see what you'll get in live mode.

Identity magic values

Matching on subject.last_name and subject.first_name ignores case. Any other name matches the identity record. Sanctions screening uses the real US Treasury OFAC list, so a made-up name like Jane Doe returns sanctions: "CLEAR".

InputResult
subject.last_name: "Nomatch"identity.name = NO_MATCH. FAIL under standard (NAME_NO_MATCH is a hard fail).
subject.last_name: "Notfound"Identity signals = NOT_FOUND.
subject.last_name: "Deceased"identity.deceased = true (DECEASED).
subject.last_name: "Thinfile"identity.data_fullness = 0.2 (THIN_FILE).
subject.last_name: "Sourceerror"Identity signals = ERROR. A simulated source outage (SOURCE_ERROR; the policy's on_source_error applies).
subject.dob: "1900-01-01"identity.dob = NO_MATCH.
subject.first_name: "Junior"identity.relative_same_name = true (NAME_SHARED_WITH_RELATIVE).
subject.first_name: "Twin"identity.lookalike_relative = true. In a Full verification with a face similarity under 95, this adds FACE_MATCH_RELATIVE_RISK.

Phone magic values

Set by the last four digits of subject.phone (E.164, e.g. +18135550199).

Phone ends inResult
0199phone_owner = NO_MATCH and phone_ported_days = 6. Typically REVIEW.
0198phone_in_service = false.
0197phone_type = VOIP.
anything elseMOBILE, in service, phone_owner = MATCH.

Email magic values

subject.emailResult
domain mailinator.comemail_disposable = true.
local part invalid (e.g. [email protected])email_valid = false.
domain starting with new (e.g. [email protected])email_domain_age_days = 5 (EMAIL_DOMAIN_NEW).
local part other (e.g. [email protected])email_owner = NO_MATCH.
anything elseValid, not disposable, email_owner = MATCH.

IP & address magic values

InputResult
context.ip: "203.0.113.50"ip_anonymous = true (IP_ANONYMOUS).
context.ip: "203.0.113.66"ip_threat = true (IP_THREAT).
context.ip: "203.0.113.77"ip_datacenter = true (IP_DATACENTER).
context.ip: "203.0.113.88"On mobile data; carrier matches the phone's. ip_carrier_match = MATCH.
context.ip: "203.0.113.89"On mobile data; a different carrier. ip_carrier_match = NO_MATCH (IP_CARRIER_MISMATCH).
context.ip: "203.0.113.99"IP in a UTC+1 time zone. Send context.timezone: "America/New_York" to get timezone_match = false (TIMEZONE_MISMATCH).
context.ip: "198.51.100.10"IP located ~1,200 mi from the address (IP_DISTANCE_HIGH).
any other IPA few miles from the address.
subject.address.line1 containing Invalidaddress_valid = false (ADDRESS_INVALID).

Phone code in test mode

No SMS is sent in test mode. The phone code only exists in a Full capture session, and in test mode it is always 000000. Submitting 000000 passes (otp = MATCH). A wrong code uses one of the 5 attempts. Send and attempt limits (3 sends, 5 attempts) and the 10-minute code lifetime still apply.

Full verification

Start a Full verification with a test key (POST /v1/full). Open its url in your browser to go through the real capture page. In test mode the page:

  • shows a Test mode badge and never emails the link (send_via is ignored)
  • accepts the phone code 000000 on the phone code step. phone is optional: if you leave it out, the test page asks for a mobile number first (any valid number works; nothing is sent)
  • uses a plain camera selfie instead of the live liveness check
  • offers a Test mode: use a sample photo button on each photo step, so you can finish without a camera or a real ID. The sample ID is a Florida driver's license for JANE ANN DOE, born 1988-04-12. If you choose Passport or Other ID card, the sample is a passport or ID card for the same person, and it passes too.
  • compares the first_name and last_name you sent with the sample ID. Send Jane and Doe to match. Another name gives ID_NAME_MISMATCH (REVIEW).

The result is set by test_outcome on POST /v1/full (default pass). It applies to every ID type:

test_outcomeDecisionReason
passPASSEverything matches
face_mismatchFAILFACE_NO_MATCH
liveness_failFAILLIVENESS_FAILED
no_face_on_documentFAILDOCUMENT_FACE_NOT_FOUND
front_mismatchFAILBARCODE_FRONT_MISMATCH (license) or MRZ_FRONT_MISMATCH (passport or ID card)
age_mismatchREVIEWAGE_ESTIMATE_MISMATCH (the selfie looks 60 to 70)
screen_photoREVIEWDOCUMENT_ON_SCREEN
blurry_idREVIEWThe ID front is rejected as blurry twice, then accepted with DOCUMENT_BLURRY

test_outcome is rejected with a live key (400 invalid_value). In a test session, the data checks use the sandbox magic values. They run on the details read from the sample ID plus the phone (yours or the one typed on the page) and the email you sent. So a phone ending 0199 still triggers PHONE_OWNER_NO_MATCH.

curl https://api.idverf.com/v1/full \
  -H "Authorization: Bearer sk_test_your_key_here" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
  "first_name": "Jane",
  "last_name": "Doe",
  "purpose": "account_opening",
  "phone": "+18135550142",
  "reference_id": "test_face_mismatch",
  "test_outcome": "face_mismatch"
}'

Open the returned url, agree, enter 000000 on the phone code step, and tap the sample photo button on each photo step. Then GET /v1/full/{id} shows status: "completed" with decision: "FAIL" and reasons: ["FACE_NO_MATCH"]. The result (GET /v1/results/{verification_id}) has checks.biometrics.face_match: "NO_MATCH". Add a test webhook endpoint to get session.started and session.completed.

Example: a PASS (data checks)

No magic values, so every signal comes back clean.

curl https://api.idverf.com/v1/data \
  -H "Authorization: Bearer sk_test_your_key_here" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
  "policy": "standard",
  "purpose": "account_opening",
  "reference_id": "test_pass_1",
  "consent": { "obtained_at": "2026-10-29T18:40:00Z", "version": "tos-2026-09" },
  "subject": {
    "first_name": "Jane", "last_name": "Doe", "dob": "1988-04-12",
    "address": { "line1": "12 Elm St", "city": "Tampa", "state": "FL", "zip": "33602" },
    "phone": "+18135550142", "email": "[email protected]"
  },
  "context": { "ip": "73.12.44.9" }
}'

Response (shortened; scores and some values are examples):

{
  "id": "ver_01JC4G7J9L1N3Q5S7U9W1Y3A5C",
  "object": "verification",
  "product": "data",
  "status": "completed",
  "decision": "PASS",
  "score": 92,
  "policy": "standard@1",
  "reasons": [],
  "checks": {
    "identity": { "name": "MATCH", "dob": "MATCH", "address": "MATCH", "deceased": false, "data_fullness": 0.81, "...": "..." },
    "contact":  { "phone_owner": "MATCH", "phone_type": "MOBILE", "phone_in_service": true,
                  "email_owner": "MATCH", "email_valid": true, "email_disposable": false, "otp": "NOT_CHECKED", "...": "..." },
    "location": { "address_valid": true, "ip_distance_mi": 2, "ip_anonymous": false, "ip_threat": false, "...": "..." }
  },
  "inputs_present": ["subject", "context"],
  "reference_id": "test_pass_1",
  "purpose": "account_opening",
  "livemode": false,
  "billing": { "units": 1, "checks_billed": ["data"] }
}

The document group didn't run (no document block). A data verification is one flat unit when at least one group runs. In the sandbox billing.units is reported but nothing is charged. If your account is on the Open tier only, identity and ownership signals return NOT_CHECKED.

Example: a REVIEW (data checks)

A phone ending in 0199 isn't registered to the person and was ported 6 days ago.

curl https://api.idverf.com/v1/data \
  -H "Authorization: Bearer sk_test_your_key_here" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
  "policy": "standard",
  "purpose": "account_recovery",
  "reference_id": "test_review_1",
  "consent": { "obtained_at": "2026-10-29T18:40:00Z", "version": "tos-2026-09" },
  "subject": {
    "first_name": "Jane", "last_name": "Doe",
    "address": { "line1": "12 Elm St", "city": "Tampa", "state": "FL", "zip": "33602" },
    "phone": "+18135550199"
  }
}'
{
  "id": "ver_01JC5H8K0M2P4R6T8V0X2Z4B6D",
  "status": "completed",
  "decision": "REVIEW",
  "reasons": ["PHONE_OWNER_NO_MATCH", "PHONE_RECENT_PORT"],
  "checks": { "contact": { "phone_owner": "NO_MATCH", "phone_ported_days": 6, "otp": "NOT_CHECKED", "...": "..." }, "...": "..." },
  "...": "..."
}

Under standard, PHONE_OWNER_NO_MATCH is a review trigger. Your app decides what to do with REVIEW. For example, send it to a manual review queue with the verification.review webhook, or ask the person to complete a Full verification.

Going live

  1. Add funds to your prepaid balance (pricing).
  2. Create an sk_live_ key. You can limit it to your server IPs.
  3. Add a live webhook endpoint and save its whsec_ secret.
  4. Check that every call sends a real purpose and consent from your user flow, and remove test_outcome from POST /v1/full requests.
  5. Set your image retention (0–7 days) under Settings → Data & privacy in the portal.
  6. Switch to the live key. Nothing else changes.

Need help testing?

See the API reference for full endpoint details, or contact support.