Under the hood of one simple API
What you send, what we check, how the decision is made and what comes back, with real request and response examples.
Full verification first. Data checks when you need them.
Both produce the same verification resource, with a product field (full or data), so one webhook handler and one decision branch cover them. Each is billed as a flat price per verification. See pricing.
Full verification
Text-message code, liveness selfie, and a photo of a US driver's license or state ID, a passport, or an ID card with machine-readable lines. Face match, name check, barcode or MRZ vs. the printed text, plus every data check your tier allows, using details read from the ID.
POST /v1/full
Data checks via API
For quick checks when a selfie isn't practical. Identity, contact, location and document checks on the details you send.
POST /v1/data
Full verification is available to every account; an open-tier account gets the open-tier data checks. Data checks that look up identity records need a reviewed (vetted) account.
How a verification session works
Full verifications run on our hosted capture page. You start one, send the person to its one-time link, and get the result by webhook. Each Full verification has a session (the link and its progress) and a result. No camera code, no image handling on your side.
-
1
Start a Full verification
POST /v1/full with the person's first and last name and a purpose. Their phone number is optional: send it if you have it. You get a one-time url, valid for 24 hours. Redirect the person to it, show it as a QR code, or set send_via to email and we send it. On a computer, the page shows a QR code so the person can switch to their phone.
-
2
The person agrees
They read and accept the biometric consent notice before anything is captured. Desktop visitors see a QR code to continue on their phone, or can use the computer's camera.
-
3
Phone code
We text a 6-digit code and they enter it. If you sent a phone number, the code goes there, which is strongest because an impostor can't swap in their own phone. If not, the person enters their own mobile number first; that number only adds weight if its owner matches the name on their ID, and a different name sends the result to REVIEW. This step comes right before the selfie, so the selfie is tied to whoever has the phone.
-
4
Live selfie
A real-time liveness check confirms a live person is present, not a photo, screen or mask.
-
5
Their ID
They pick a driver's license or state ID, a passport, or another ID card (US passport card, green card, work permit, or a national ID card). For a license they photograph both sides, and the back barcode is read in the browser. For a passport they photograph the photo page, and we read the machine-readable lines (MRZ) at the bottom. For an ID card they photograph both sides, and we read the MRZ on the back.
-
6
We decide
We compare the selfie with the ID photo and the name you sent with the name on the ID. We check the barcode or MRZ against the printed text, run document and data checks, then decide PASS, REVIEW or FAIL and send webhooks. The person is sent to your redirect_url if you gave one.
Request
POST /v1/full
Authorization: Bearer sk_test_••••
Idempotency-Key: 3c1d…
{
"first_name": "Jane",
"last_name": "Doe",
"purpose": "account_opening",
"phone": "+18135550142",
"reference_id": "user_88123",
"redirect_url": "https://example.com/done"
}
Response · 201
{
"id": "ses_01M6…",
"object": "session",
"type": "full",
"status": "created",
"url": "https://www.idverf.com/verify/rXhQ…",
"verification_id": "ver_01M6…",
"steps": { "consent": false, "otp": false, "selfie": false,
"document_front": false, "document_back": false },
"decision": null,
"expires_at": "…",
"images_deleted_at": null
}
Statuses
created → in_progress → processing → completed, or expired if the link isn't finished in 24 hours. Expired sessions are refunded.
Webhooks
session.started, session.completed and session.expired, plus the usual verification events. data is the result with data.session attached. Fetch it any time from GET /v1/results/{id}.
Photos for review
Your team can view the selfie and ID photos in the portal to review a result until they're deleted (at most 7 days).
Data checks via API
For quick checks when a selfie isn't practical. One request in, one decision out. No photos, just the details you already have.
-
1
You send
Name, DOB and address from the ID, plus phone, email, IP and the document fields you have. Add the purpose and when the user consented.
-
2
We check
Identity, contact, location and document checks run in parallel against authoritative data sources, carrier data and in-house forensic logic.
-
3
You decide
Get PASS, REVIEW or FAIL with a 0–100 score, and reason codes. Typically in under two seconds.
Request
POST /v1/data
Authorization: Bearer sk_test_••••
Idempotency-Key: 7f3c9a1e-…
{
"policy": "standard",
"purpose": "account_opening",
"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]"
},
"document": { "type": "drivers_license", "…": "…" },
"context": { "ip": "73.12.44.9" }
}
Response
{
"id": "ver_01JBX9Q4…",
"object": "verification",
"product": "data",
"status": "completed",
"decision": "REVIEW",
"score": 64,
"reasons": ["PHONE_OWNER_NO_MATCH", "PHONE_RECENT_PORT"],
"checks": {
"identity": { "name": "MATCH", "dob": "PARTIAL",
"address": "MATCH", "deceased": false },
"contact": { "phone_owner": "NO_MATCH",
"phone_ported_days": 6,
"email_owner": "MATCH" },
"location": { "ip_distance_mi": 3, "ip_anonymous": false },
"document": { "barcode_front_match": "MATCH",
"expired": false, "real_id": "COMPLIANT" }
},
"billing": { "units": 1, "checks_billed": ["data"] }
}
{
"id": "ver_01JBX9Q4…",
"object": "verification",
"product": "data",
"status": "completed",
"decision": "PASS",
"score": 91,
"reasons": [],
"checks": {
"identity": { "name": "MATCH", "dob": "MATCH",
"address": "MATCH", "deceased": false },
"contact": { "phone_owner": "MATCH",
"phone_in_service": true,
"email_owner": "MATCH" },
"location": { "ip_distance_mi": 3, "ip_anonymous": false },
"document": { "barcode_front_match": "MATCH",
"expired": false, "real_id": "COMPLIANT" }
},
"billing": { "units": 1, "checks_billed": ["data"] }
}
Five check groups. One answer.
Send what you have — checks that need a missing input simply return NOT_CHECKED. The biometrics group fills in during Full verification: liveness (PASS/FAIL) and liveness_confidence, face_match and face_similarity, document_face_detected, document_front_readable, id_type, barcode_read or mrz_read, and id_name_match.
Identity
Do the name, address and date of birth belong together in authoritative identity data sources?
- Name, address & DOB match
- Deceased indicator
- Identity data fullness
- Length of residence & recent move
- US sanctions list (OFAC) screening
- Repeat use of an ID, phone or IP in your account
Contact
Is the phone and email really theirs, and are they risky?
- Phone & email ownership
- Line type, in-service, recent port
- Disposable & invalid email
- One-time code by text (Full)
Location
Is the address real, and is the user actually near it?
- Postal address validation
- Residential vs. business
- IP distance, VPN/proxy, threat
- Device geolocation distance
Document
Does the ID hold up to forensic logic?
- Barcode (AAMVA) structure
- Barcode vs. card front
- License number format & encoding
- Passport and ID card MRZ check digits, expiry & age
Biometrics
Is a live person present, and are they the person on the ID? Runs in Full verification.
- Liveness (real, present person)
- Selfie vs. ID photo face match
- Name you sent vs. name on the ID
- ID readable, barcode or MRZ read
A decision you can act on
Every verification returns three things, so your code can branch on one field and your team can see exactly why.
- decision
- PASS, REVIEW or FAIL, set by your policy's hard-fail rules and score thresholds.
- score
- 0–100. Higher means more likely genuine. Positive evidence raises it; risk signals lower it.
- reasons
- Machine-readable codes like PHONE_RECENT_PORT or DOCUMENT_EXPIRED, most severe first.
What to do with each result
-
PASS
Let them in.
-
REVIEW
Send it to your team. The verification.review webhook makes a review queue easy. For a data check, you can also ask the person to complete a Full verification.
-
FAIL
Stop. The reason codes say why.
Under the standard policy: below 30 fails, 75 and above passes, everything between goes to review.
Most verifications pass without a human. Your policy decides what goes to review.
Illustrative example only — not real customer data. Your mix depends on your traffic and policy.
No personal data out.
IDVerf tells you whether what you sent matches — it never tells you anything you didn't already know. Responses, webhooks and logs carry signals only: MATCH, NO_MATCH, booleans and numbers. Never a stored name, address, phone, email, date or image — including the details read from an ID in a Full verification.
That means you can't use IDVerf to look people up — and neither can anyone who gets hold of your keys.
Short retention
Raw inputs purged after 90 days by default — configurable down to 0.
Purge on demand
DELETE /v1/results/{id}/inputs removes stored inputs instantly.
Encrypted at rest
Inputs and capture photos are encrypted; secret keys are stored only as hashes.
Photos: 7 days max
Selfie and ID images are kept 0–7 days (your setting, default 3) for review in the portal, then deleted. Face measurements are never stored.
Consent in the flow
People accept a biometric consent notice before capture; it is recorded with the session.
Your risk appetite, as a policy
Pick a built-in policy or write your own: which checks run, what fails outright, and what sends to review. Full verifications use your chosen policy plus hard fails for liveness, face mismatch, no face on the ID, barcode or MRZ mismatch and a failed code. They send a phone owner mismatch, a name that doesn't match the ID, or an unreadable barcode or MRZ to review. Custom policies can include biometrics in checks.
Contact, location and document checks. No identity data needed — available to every account.
All four groups. Fails on deceased, name mismatch, expired or tampered ID. The default for most.
All four groups with tighter thresholds and more hard-fail and review rules.
For people outside the US. Leans on the ID, face, email and network. US-only record checks are skipped, not held against them.
Your own checks, hard-fail list, review triggers, thresholds and minimum age. Versioned automatically.
Built for developers
A small, predictable REST API with the conventions you already know.
-
Free sandbox
sk_test_ keys never touch live data and cost nothing. Magic values and test_outcome let you trigger every outcome, including Full verifications with sample photos.
-
Idempotent by design
Every POST takes an Idempotency-Key. Retries within 24 hours return the original result — and aren't billed twice.
-
Signed webhooks
Results, review and session events, signed with HMAC-SHA256 and retried for 24 hours.
-
Clear errors
Stable error types and codes, the offending param, and a request id for every call.
# Retry-safe: same key, same result, billed once
curl https://api.idverf.com/v1/data \
-H "Authorization: Bearer $IDVERF_KEY" \
-H "Idempotency-Key: $(uuidgen)" \
-H "Content-Type: application/json" \
-d @request.json
# Webhook delivery
POST https://your-app.example/hooks/idverf
IDVerf-Signature: t=1793990463,v1=5f2b…
{
"id": "evt_01JBXA…",
"type": "verification.review",
"data": { "id": "ver_01JBX9Q4…",
"decision": "REVIEW", … }
}
Ready to build?
Create an account for free sandbox keys, then follow the API reference to make your first call.