Skip to content
IDVERF
The IDVerf platform

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 Hosted session

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 API only

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. 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. 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. 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. 4

    Live selfie

    A real-time liveness check confirms a live person is present, not a photo, screen or mask.

  5. 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. 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. 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. 2

    We check

    Identity, contact, location and document checks run in parallel against authoritative data sources, carrier data and in-house forensic logic.

  3. 3

    You decide

    Get PASS, REVIEW or FAIL with a 0–100 score, and reason codes. Typically in under two seconds.

PASS — let them in REVIEW — check by hand FAIL — stop

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

  1. PASS

    Let them in.

  2. 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.

  3. FAIL

    Stop. The reason codes say why.

How scores map to decisions
Illustrative

Under the standard policy: below 30 fails, 75 and above passes, everything between goes to review.

Decision mix
Illustrative

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.

Privacy by design

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.

basic Pass ≥ 60

Contact, location and document checks. No identity data needed — available to every account.

standard Pass ≥ 75

All four groups. Fails on deceased, name mismatch, expired or tampered ID. The default for most.

strict Pass ≥ 85

All four groups with tighter thresholds and more hard-fail and review rules.

international Pass ≥ 70

For people outside the US. Leans on the ID, face, email and network. US-only record checks are skipped, not held against them.

custom You decide

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.