Skip to content
IDVERF

API reference · v1

IDVerf API

IDVerf checks that a person is who they say they are. Full verification sends them to a hosted page to confirm a one-time code, take a liveness selfie and photograph their ID (a US driver's license or state ID, a passport, or an ID card with machine-readable lines). When a selfie isn't practical, data checks via API run on details you already have. We match faces and check details against identity records, carrier data and document checks. Then we return a PASS REVIEW or FAIL decision with match signals.

REST + JSON

Standard HTTP methods and status codes. UTF-8 JSON bodies.

One object

Full and Data both produce the same result object. One handler covers both.

Free sandbox

sk_test_ keys with magic values. Testing guide.

Base URL & environments

https://api.idverf.com/v1

The key sets the mode, not the URL. sk_live_ keys run live checks and are billed. sk_test_ keys run in the free sandbox on the same base URL. Test keys also work with https://sandbox.api.idverf.com/v1 if you want a separate host.

HTTPS only (TLS 1.2+). Request and response bodies are UTF-8 JSON (Content-Type: application/json). A data-only verification aims to return in under 2 seconds at p95.

Authentication

Send a secret key in the Authorization header of every request. Create and revoke keys in the portal under Developers → API keys. Use secret keys on your server only. Never put them in a browser or mobile app.

curl https://api.idverf.com/v1/checks \
  -H "Authorization: Bearer sk_test_your_key_here"
PrefixUse
sk_live_Live mode. Real data sources, real SMS, billed from your prepaid balance.
sk_test_Sandbox. Simulated sources with magic values, no SMS, free.
pk_Reserved for a future embeddable capture SDK. Not accepted by v1 endpoints.

You can limit a key to an IP allow-list. Calls from other addresses return 403 ip_not_allowed. A missing or invalid key returns 401 invalid_key.

Versioning

The major version is in the path (/v1). We add new fields, checks, enum values and reason codes without changing the version. Your client must ignore unknown fields. It should also handle unknown enum values without breaking. For example, treat an unknown signal value like NOT_CHECKED.

Idempotency

An Idempotency-Key header is required on every POST. Use a new value (a UUID works well) for each operation, and send the same value when you retry it.

  • Replays with the same key and the same body within 24 hours return the original response and are not billed again.
  • Reusing a key with a different body returns 409 idempotency_mismatch.
  • Retrying while the original request is still running returns 409 idempotency_in_progress. Wait and retry.
  • A POST without the header returns 400 missing_field with param: "Idempotency-Key".
Idempotency-Key: 7f3c9a1e-5b2d-4e8a-9c61-0d2f4b7a8e13

IDs & timestamps

Object IDs are prefixed ULIDs, so they sort by creation time.

PrefixObject
ver_Verification result (Full and Data)
ses_Session: the link and progress of a Full verification
pol_Policy
whk_Webhook endpoint
evt_Webhook event
req_Request id, returned in errors. Include it when you contact support.

All timestamps are ISO 8601 in UTC, e.g. 2026-10-29T18:41:02Z. Dates are YYYY-MM-DD.

Rate limits

Limits apply per API key: by default 20 requests per second and 1,000 requests per minute. Every response includes these headers:

HeaderMeaning
X-RateLimit-LimitRequests allowed in the current window
X-RateLimit-RemainingRequests left in the current window
X-RateLimit-ResetUnix time when the window resets
Retry-AfterOn 429 only: seconds to wait before retrying

Over the limit, you get 429 too_many_requests. Back off for Retry-After seconds and retry with the same Idempotency-Key. Need higher limits? Contact support.

Errors

Errors use standard HTTP status codes and one JSON shape. type is the general category. code is the specific cause. param, when present, names the field at fault.

{
  "error": {
    "type": "invalid_request",
    "code": "missing_field",
    "message": "subject.last_name is required",
    "param": "subject.last_name",
    "request_id": "req_01JC3K8W5T2B7Q9R4M6N1P0XYZ"
  }
}
HTTPtypecodeWhen
400 invalid_request
missing_fieldinvalid_formatinvalid_value
A required field is missing, malformed or out of range. param names the field.
401 authentication
invalid_key
Missing, malformed, revoked or unknown API key.
402 billing
insufficient_balance
Prepaid balance too low for a live call. Top up in the portal.
403 permission
entitlement_requiredpurpose_not_permittedip_not_allowedaccount_suspendedbuiltin_policy
Account not entitled, purpose not approved, caller IP not on the key's allow-list, account suspended, or an attempt to modify a built-in policy.
404 not_found
verification_not_foundsession_not_foundpolicy_not_foundwebhook_not_foundroute_not_found
The resource or route does not exist (or belongs to another account or mode).
405 invalid_request
method_not_allowed
HTTP method not supported on this path.
409 conflict
idempotency_mismatchidempotency_in_progressinvalid_state
Idempotency key reused with a different body, the original request is still running, or the action is not valid in the resource's current state.
429 rate_limit
too_many_requests
Rate limit exceeded (see Retry-After).
5xx api_error
upstream_unavailablebiometrics_unavailableinternal_error
Something went wrong on our side, or live capture sessions are temporarily unavailable (503). Safe to retry with the same Idempotency-Key.
A data source outage doesn't fail the verification. It still completes. The affected signals return ERROR, the reason SOURCE_ERROR is added, and the policy's on_source_error setting decides whether that forces REVIEW.

Core concepts

Products

A Full verification has two parts: a session (the link and its progress) and a result. Data checks just have a result. Results of both are fetched from /v1/results, and their product field says which product. Each is billed as one flat unit (see Pricing).

productStart withWhat runsBilled
fullPOST /fullOne-time code by text, liveness selfie, photos of a US driver's license or state ID (front and back), a passport photo page, or another ID card (front and back), face match, barcode or MRZ vs. the printed text, plus identity, contact, location and document checks using details read from the ID.Per verification (texts included)
dataPOST /dataData checks via API, for when a selfie isn't practical: runs on the details you send, with no selfie or ID photos.Per verification, only if at least one check group runs

Full verification is the main product. Data checks via API are for quick checks where a selfie isn't practical. Data checks that look up identity records need a vetted account. In a Full verification, an open-tier account gets only the open-tier data checks.

The verification

A verification (the result) is the main resource. It holds the inputs sent so far, the checks that ran, and the decision. In the API it has object: "verification" and a ver_ id. For data checks, only the subject's name, purpose and consent are required. Checks with missing inputs return NOT_CHECKED.

Statuses

statusMeaning
processingChecks running (async requests only).
awaiting_inputFull only: waiting for the person to finish the hosted capture page.
completedDecision is final for the current inputs.
expiredA capture link wasn't finished within 24 hours (refunded, no decision).
failedCould not run (all sources down, or invalid inputs). Not billed.

Decision, score & reasons

  • decision: PASS REVIEW FAIL, or null while processing.
  • score: 0–100, higher means more likely genuine. The policy's pass_score and fail_score turn it into a decision. hard_fail and review_if reasons override the score.
  • reasons[]: codes that explain the result, most severe first. See Reason codes.

Results are signals, not certainties. Your application makes the final decision about the user.

Signal values

All match signals use this enum:

ValueMeaning
MATCHInput agrees with the source.
PARTIALPartly agrees (e.g. DOB year ±1, street only).
NO_MATCHThe source has the person, but the input disagrees.
NOT_FOUNDThe source has no record to compare.
NOT_CHECKEDInput missing, check not in the policy, or not entitled.
ERRORThe source failed.

Other signals are booleans, numbers or the enums listed in the check catalog. No signal ever contains a stored name, address, phone, email or date.

Policies

A policy sets which check groups run, which reasons fail or send to review, and the score thresholds. The built-in policies are basic, standard, strict and international (details). Create your own with POST /policies. Each update creates a new version, name@n. Every verification records the version it ran under.

Entitlements

Your tier decides which checks you can run. We set it during onboarding based on your use case.

  • open: any verified account. Contact risk, IP and geolocation, postal address validation, all document forensics, biometrics (liveness and face match) and the phone code in Full verification.
  • vetted: we reviewed your use case at onboarding. Adds identity record matching and phone/email ownership.
  • credentialed: enhanced review plus a GLBA permissible purpose. Reserved for future high-sensitivity checks.

A check you aren't entitled to returns NOT_CHECKED and isn't billed. Saving a policy that requires such a check fails with 403 entitlement_required. GET /checks shows your tier and entitlements. Apply for a higher tier in the portal under Access.

People outside the US

US identity records, the phone-owner check, phone carrier lookups and postal address validation only cover the US. We skip them when the ID was issued outside the US, the address is outside the US, or the phone number isn't a +1 number. Skipped checks return NOT_CHECKED and don't count against the person. We don't verify identity records for people outside the US.

These still run for everyone: liveness and face match, the passport and ID card checks, email checks, IP and network checks, the device time zone, sanctions screening and repeat use.

  • Use the built-in international policy ("policy": "international") on POST /full or POST /data. It relies on the ID, face, email and network, with lower score thresholds (details).
  • Send subject.address.country (ISO 3166-1 alpha-2) for a non-US address. It defaults to US. For other countries, state and zip are free-form.
  • A phone number typed in on the hosted page must be a US number. To use an international number, send it yourself in phone.

Full verification

Start a Full verification

POST /v1/full

A Full verification has a session (the link and its progress, ses_ id) and a result (ver_ id). This call creates both and returns a one-time url valid for 24 hours. Redirect the person to it, show it as a QR code, or set send_via: "email" and we email it. If opened on a computer, the page shows a QR code so the person can switch to their phone. You can also create links and QR codes in the portal. The product price is held from your balance now and refunded if the link expires. Returns 201 with the session object. Its verification_id is the id of the result.

The name is required. Send the person's first_name and last_name. We compare them with the name on the ID (checks.biometrics.id_name_match). If they don't match, the result goes to REVIEW (ID_NAME_MISMATCH). If the ID can't be read, we use the name you sent for the phone and email ownership checks.
The phone number is optional. If you send phone, we text the one-time code to that number. This is the strongest option, because an impostor can't swap in their own phone. If you leave it out, the person enters their own US mobile number on the hosted page before the code is sent. A code only confirms the number it was sent to. A number the person typed in only adds weight if the phone-owner check matches the name on their ID. If that check shows a different name, the result goes to REVIEW (PHONE_OWNER_NO_MATCH). The verification's otp.phone_source shows which way it went: customer or person.

Request body

FieldTypeRequiredNotes
type enum No Optional. Only full is accepted (the default). Any other value returns 400 invalid_value.
first_name string Yes The person's first name. Compared with the name on the ID.
last_name string Yes The person's last name. Compared with the name on the ID.
middle_name string No Optional. Compared with the middle name on the ID (an initial matches), and used in the identity record search.
address object No Optional. Same shape as subject.address in data checks: line1, line2, city, state, zip, country. Compared with the address on a license (does the person match the license) and with the identity records (did the person give you a true address). Passports and ID cards have no address, so for those this one is also used for the location checks.
purpose enum Yes Same purposes as data checks; must be on your approved list.
phone string No Optional. E.164, e.g. +18135550142. If you send it, the one-time code is texted here and the person can't change it. If you leave it out, the person enters their own US mobile number on the hosted page. Either way the number is used in the contact checks.
email string No Used in the contact checks and for send_via: "email".
policy string No Policy id or built-in name; default standard. Use international for people outside the US.
reference_id string No Your own id, max 128 chars.
redirect_url string No https URL the person is sent to when they finish.
consent object No obtained_at and version, if you also collected consent in your own flow. IDVerf always collects biometric consent on the capture page.
send_via enum No email. We email the link for you. Omit it to share the url yourself (redirect or QR code). Test keys never send anything.
test_outcome enum No Test keys only: pass, face_mismatch, liveness_fail, no_face_on_document, front_mismatch, age_mismatch, screen_photo, blurry_id. See the sandbox guide.

Example

curl https://api.idverf.com/v1/full \
  -H "Authorization: Bearer sk_test_your_key_here" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 5e2a9c71-4b3d-4f80-a1c6-7d9e0b2f3a14" \
  -d '{
  "first_name": "Jane",
  "last_name": "Doe",
  "purpose": "account_opening",
  "phone": "+18135550142",
  "email": "[email protected]",
  "reference_id": "smoke-1",
  "redirect_url": "https://example.com/verified"
}'
{
  "id": "ses_01M6Z3K8Q2W5R7T9V1X3Z5B7D9",
  "object": "session",
  "type": "full",
  "status": "created",
  "url": "https://www.idverf.com/verify/rXhQ8a2LmN4pQ6sT8vX0zB2dF4hJ6kM8nP0rS2tV",
  "verification_id": "ver_01M6Z3K8Q3A5C7E9G1J3L5N7P9",
  "steps": { "consent": false, "otp": false, "selfie": false, "document_front": false, "document_back": false },
  "decision": null,
  "score": null,
  "reasons": [],
  "reference_id": "smoke-1",
  "livemode": false,
  "created_at": "2026-11-02T15:04:05Z",
  "expires_at": "2026-11-03T15:04:05Z",
  "completed_at": null,
  "images_deleted_at": null
}

The url is returned only here. We store only a hash of its token. Errors: 400 missing_field / invalid_value (for example a missing first_name or last_name, a malformed phone, a type other than full, or test_outcome with a live key), 400 invalid_format (redirect_url not https), 402 insufficient_balance, 403 purpose_not_permitted, 503 biometrics_unavailable.

The session object

FieldTypeNotes
idstringses_...
objectstringsession
typeenumAlways full.
statusenumcreated (link not opened yet), in_progress (person is going through the steps), processing (all steps done, checks running), completed (decision ready), expired (not finished within 24 hours; refunded).
urlstringThe one-time capture link. Returned only in the create response; null when you get or list sessions.
verification_idstringThe id of the result (ver_...). Fetch it from GET /results/{id} for the check-level result.
stepsobjectconsent, otp, selfie, document_front, document_back: true once done. A passport has no back, so document_back is left out once the person picks Passport. ID cards have a back.
decision, score, reasonsmixedCopied from the result once completed; null / [] before.
reference_idstringEchoed.
livemodebooleantrue for sk_live_ keys.
created_at, expires_at, completed_attimestamp
images_deleted_attimestampWhen the photos were deleted under your image retention setting.

The hosted capture flow

What the person sees at the url:

  1. Consent. They read the biometric consent notice and tap I agree. Nothing is captured before this. The agreement is recorded with the session.
  2. Phone code. We text a 6-digit code to the phone you sent. If you didn't send one, they first enter their own mobile number. They enter the code (up to 3 sends, 5 attempts). This step comes right before the selfie, which ties the selfie to whoever has the phone.
  3. Liveness selfie. A short real-time check confirms a live person is there.
  4. Choose an ID. They pick Driver's license or state ID, Passport or Other ID card. We accept US driver's licenses and state ID cards, passports from any country, and ID cards with machine-readable lines (MRZ) on the back: a US passport card, green card (permanent resident card), work permit (employment authorization card), or a national ID card from another country.
  5. ID front. A photo of the front of the license or ID card (the photo side), or of the passport photo page. For a passport we read the MRZ (the machine-readable lines at the bottom).
  6. ID back (licenses and ID cards). A photo of the back. For a license, the browser reads the PDF417 barcode. For an ID card, we read the MRZ. Passports skip this step.
  7. Done. They're sent to redirect_url if you gave one.

On a computer, the person can scan a QR code to continue on their phone, or use the computer's camera. When the steps are done, we compare the selfie with the ID photo and the name you sent with the name on the ID. For a license, we check the barcode against the text on the card front (checks.document.barcode_front_match) and run document checks. We also run data checks using the name, address, date of birth and license details from the barcode. For a passport, we check the MRZ check digits and expiry (checks.document.mrz_valid), compare the MRZ with the printed text (mrz_front_match; a mismatch is MRZ_FRONT_MISMATCH, a hard fail), and run data checks on the name and date of birth. A passport has no address, so address checks don't run. For an ID card, we read the MRZ on the back, check its check digits and expiry, compare it with the printed front, and match the face to the card photo. For IDs issued outside the US, the US-only checks are skipped (see People outside the US). We also use the phone (yours or the one the person entered) and the email you sent. Then we decide and send session.completed and verification.completed (and verification.review on REVIEW). When someone on your team approves or rejects a REVIEW result in the portal, we send verification.reviewed. With the photo setting “Delete right after the check, unless it needs review”, a REVIEW result keeps its photos until that decision (at most 7 days); every other result’s photos are deleted as soon as it’s decided.

Photos. Photos are not included in results or webhooks. They are stored encrypted for your image retention period (0–7 days, default 3; Settings → Data & privacy in the portal) so your team can review them in the portal. Then they are deleted. Face measurements are not stored.

Decision rules

  • Sessions use your chosen policy plus hard fail on LIVENESS_FAILED, FACE_NO_MATCH, DOCUMENT_FACE_NOT_FOUND, BARCODE_FRONT_MISMATCH, MRZ_FRONT_MISMATCH, OTP_FAILED, and review on BARCODE_UNREADABLE, MRZ_UNREADABLE, DOCUMENT_FRONT_UNREADABLE, DOCUMENT_FRONT_PARTIAL (one detail not found in the printed text), PHONE_OWNER_NO_MATCH, LIVENESS_LOW, ID_NAME_MISMATCH, FACE_MATCH_RELATIVE_RISK.
  • Liveness: a confidence of 70 or more passes. From 50 to 69 the result goes to review (LIVENESS_LOW). Under 50 fails (LIVENESS_FAILED). If a selfie scores under 70, the person is asked to try again, up to 3 times, and the best attempt counts.
  • If the barcode or MRZ can't be read, we use the name you sent for the phone and email ownership checks, and id_name_match is NOT_CHECKED.
  • If the person typed in the phone number, a passed code only adds to the score when the phone-owner check matches the name on their ID.

Get a session

GET /v1/full/{id}

Returns the session object (with url: null), so you can see how far the person has got. Use the ses_ id. Unknown ids return 404 session_not_found. For the check-level result, fetch GET /results/{verification_id}.

curl https://api.idverf.com/v1/full/ses_01M6Z3K8Q2W5R7T9V1X3Z5B7D9 \
  -H "Authorization: Bearer sk_test_your_key_here"

List sessions

GET /v1/full

Sessions of Full verifications for the key's mode, newest first. Query params: limit (1–100, default 20), status (created, in_progress, processing, completed, expired) and starting_after (a ses_ id; use next_cursor). Returns { "object": "list", "data": [ session, ... ], "has_more": false, "next_cursor": null }.

Full results

When the person finishes, the result is a normal result object (fetch it with GET /results/{verification_id}) with product: "full" and session_id set. It includes a checks.biometrics group (fields in the check catalog).

{
  "id": "ver_01M6Z3K8Q3A5C7E9G1J3L5N7P9",
  "object": "verification",
  "product": "full",
  "session_id": "ses_01M6Z3K8Q2W5R7T9V1X3Z5B7D9",
  "status": "completed",
  "decision": "PASS",
  "score": 88,
  "policy": "standard@3",
  "reasons": [],
  "checks": {
    "biometrics": { "liveness": "PASS", "liveness_confidence": 97, "face_match": "MATCH",
                    "face_similarity": 99, "document_face_detected": true,
                    "document_front_readable": true, "id_type": "drivers_license",
                    "barcode_read": true, "mrz_read": null, "id_name_match": "MATCH" },
    "document":   { "barcode_valid": true, "barcode_front_match": "MATCH", "number_format": "MATCH",
                    "expired": false, "...": "..." },
    "contact":    { "otp": "MATCH", "...": "..." },
    "identity":   { "...": "..." },
    "location":   { "...": "..." }
  },
  "images_deleted_at": null,
  "billing": { "units": 1, "checks_billed": ["full"] },
  "...": "..."
}

Scores and similarity values above are examples. For a passport or ID card, id_type is passport or id_card, barcode_read is null, mrz_read is true or false, and checks.document.mrz_valid is set. document.type can be id_card. The identity, contact and location groups use the same fields as a data verification.

Data checks

Run data checks

POST /v1/data

Data checks via API, for when a selfie isn't practical. Runs checks on details you already have and returns a result, with no selfie or ID photos. Required: subject.first_name, subject.last_name, purpose and consent. Everything else is optional. The more you send, the more checks can run. Returns 200 with the result object.

Async. Add ?async=true to get 202 Accepted immediately with status: "processing" and decision: null. A verification.completed webhook fires when it finishes. You can also poll GET /results/{id}.

Request body

FieldTypeRequiredNotes
policy string No Policy id (pol_...) or built-in name (basic, standard, strict, international). Defaults to the account default policy.
purpose enum Yes account_opening, account_recovery, age_verification, fraud_prevention, transaction_authorization. Must be on your account's approved list.
reference_id string No Your own id for this user or transaction, max 128 chars. Searchable.
consent.obtained_at timestamp Yes When the end user agreed (ISO 8601 UTC).
consent.version string Yes Version of your consent text the user agreed to.
subject.first_name string Yes
subject.last_name string Yes
subject.middle_name string No
subject.dob date No YYYY-MM-DD
subject.address object No line1, line2, city, state, zip, country. country is ISO 3166-1 alpha-2 and defaults to US. US addresses need a 2-letter state and 5-digit ZIP; for other countries state and zip are free-form.
subject.phone string No E.164, e.g. +18135550142
subject.email string No
document.type enum No drivers_license, state_id, passport, passport_card, id_card
document.issuing_state string No USPS state code, e.g. FL
document.issuing_country string No ISO 3166-1 alpha-2, e.g. US
document.number string No
document.issue_date date No YYYY-MM-DD
document.expiry_date date No YYYY-MM-DD
document.barcode_raw string No Raw PDF417 payload (AAMVA). Enables barcode checks.
document.mrz string No Raw MRZ lines, newline-separated. Enables MRZ checks.
context.ip string No The end user's IP address, not your server's.
context.user_agent string No The end user's browser user agent.
context.geolocation object No lat, lng, accuracy_m, permission (granted, denied, unavailable)
context.timezone string No The device's IANA time zone, e.g. America/New_York (in a browser: Intl.DateTimeFormat().resolvedOptions().timeZone). Enables checks.location.timezone_match. Invalid values return 400 invalid_format.

Example request

curl https://api.idverf.com/v1/data \
  -H "Authorization: Bearer sk_test_your_key_here" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 7f3c9a1e-5b2d-4e8a-9c61-0d2f4b7a8e13" \
  -d '{
  "policy": "standard",
  "purpose": "account_opening",
  "reference_id": "user_88123",
  "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", "issuing_state": "FL", "number": "D123-456-88-412-0",
    "issue_date": "2022-05-01", "expiry_date": "2030-04-12",
    "barcode_raw": "@\n\u001e\rANSI 636010..."
  },
  "context": {
    "ip": "73.12.44.9",
    "timezone": "America/New_York",
    "geolocation": { "lat": 27.95, "lng": -82.46, "accuracy_m": 12, "permission": "granted" }
  }
}'

Example response

200 OK. Here the phone isn't registered to Jane and was ported 6 days ago, so the standard policy returns REVIEW.

{
  "id": "ver_01JBX9Q4M2T7K8R3W5Z6N0P1QA",
  "object": "verification",
  "product": "data",
  "session_id": null,
  "status": "completed",
  "decision": "REVIEW",
  "score": 64,
  "policy": "standard@3",
  "reasons": ["PHONE_OWNER_NO_MATCH", "PHONE_RECENT_PORT"],
  "checks": {
    "identity": { "name": "MATCH", "dob": "PARTIAL", "address": "MATCH",
                  "deceased": false, "data_fullness": 0.81, "residence_years": 4,
                  "sanctions": "CLEAR", "document_reuse": 0, "phone_reuse": 0 },
    "contact":  { "phone_owner": "NO_MATCH", "phone_type": "MOBILE", "phone_in_service": true,
                  "phone_ported_days": 6, "email_owner": "MATCH", "email_valid": true,
                  "email_disposable": false, "email_domain_age_days": null, "otp": "NOT_CHECKED" },
    "location": { "address_components": { "street_number": "MATCH", "street": "MATCH", "city": "MATCH",
                    "state": "MATCH", "zip": "MATCH", "zip4": "MATCH", "county": "MATCH" },
                  "address_type": "RESIDENTIAL", "ip_distance_mi": 3, "ip_anonymous": false,
                  "ip_datacenter": false, "timezone_match": true,
                  "geo_distance_mi": 1, "geo_accuracy_m": 12, "geo_permission": "granted" },
    "document": { "barcode_valid": true, "barcode_front_match": "MATCH", "number_format": "MATCH",
                  "number_encodes_name_dob": "MATCH", "expired": false, "years_since_issue": 4,
                  "real_id": "COMPLIANT", "holder_age": 38, "holder_age_at_issue": 34 }
  },
  "inputs_present": ["subject", "document", "context"],
  "reference_id": "user_88123",
  "purpose": "account_opening",
  "livemode": false,
  "created_at": "2026-10-29T18:41:02Z",
  "completed_at": "2026-10-29T18:41:03Z",
  "inputs_purged_at": null,
  "otp": null,
  "images_deleted_at": null,
  "billing": { "units": 1, "checks_billed": ["data"] }
}

The check groups shown are examples. Fields you aren't entitled to, or whose inputs you didn't send, may be left out or returned as NOT_CHECKED. Always ignore unknown fields.

Results

The result object

The result of a Full verification or data checks. It has object: "verification" and a ver_ id. Returned by POST /data and GET /results/{id}, and carried in webhook data.

FieldTypeNotes
idstringver_...
objectstringverification
productenumfull or data. See Products.
session_idstringses_... for Full verifications; otherwise null.
statusenumprocessing, awaiting_input (Full only), completed, expired, failed. See Statuses.
decisionenumPASS, REVIEW, FAIL; null while processing.
scoreint0–100, higher = more likely genuine.
policystringPolicy applied, with its version, e.g. standard@3.
reasonsstring[]Reason codes, most severe first.
checksobjectGrouped results: identity, contact, location, document, biometrics. See Check catalog.
inputs_presentstring[]Which input blocks were supplied (no values).
reference_idstringEchoed.
purposestringEchoed.
livemodebooleantrue for sk_live_ keys, false for sk_test_.
created_attimestamp
completed_attimestampnull while processing.
inputs_purged_attimestampWhen stored inputs were purged (retention or DELETE); otherwise null.
otpobjectFull only. status, sends_remaining, attempts_remaining, expires_at and phone_source once a code has been sent; otherwise null. phone_source is customer (you sent phone in POST /full) or person (the person typed their number on the hosted page).
images_deleted_attimestampWhen capture photos were deleted under your image retention setting; otherwise null.
reviewobjectSet when someone on your team approves or rejects a REVIEW result in the portal: decision (PASS or FAIL), note and reviewed_at. The automated decision is kept unchanged. Otherwise null.
billingobjectunits (int) and checks_billed (string[]), e.g. {"units": 1, "checks_billed": ["full"]}.

Billing

Each verification is one unit of its product: "billing": { "units": 1, "checks_billed": ["data"] } (or ["full"]). A data verification where every group returned only NOT_CHECKED isn't billed (units: 0). For Full verification, the price is held when the session is created and refunded if the link expires. Texts inside a Full verification are included. Idempotent replays and failed verifications aren't billed. Sandbox (sk_test_) usage is always free. See Pricing.

Get a result

GET /v1/results/{id}

Returns the result object for a Full verification or data checks. Use the ver_ id (for Full, the session's verification_id). Unknown ids (or ids from the other mode) return 404 verification_not_found.

curl https://api.idverf.com/v1/results/ver_01JBX9Q4M2T7K8R3W5Z6N0P1QA \
  -H "Authorization: Bearer sk_test_your_key_here"

List results

GET /v1/results

Returns results of Full verifications and data checks for the key's mode, newest first, with cursor pagination.

Query paramNotes
reference_idExact match on your reference id.
created_afterISO 8601 timestamp. Only results created after it.
created_beforeISO 8601 timestamp. Only results created before it.
decisionPASS, REVIEW or FAIL.
productfull or data.
statusprocessing, awaiting_input, completed, expired or failed.
limit1–100, default 20.
starting_afterA ver_ id (use next_cursor) to fetch the next page.
curl -G https://api.idverf.com/v1/results \
  -H "Authorization: Bearer sk_test_your_key_here" \
  -d decision=REVIEW -d limit=2
{
  "object": "list",
  "data": [
    { "id": "ver_01JBX9Q4M2T7K8R3W5Z6N0P1QA", "status": "completed", "decision": "REVIEW", "score": 64, "...": "..." },
    { "id": "ver_01JBX7H2C9D4E5F6G7H8J9K0LM", "status": "completed", "decision": "REVIEW", "score": 58, "...": "..." }
  ],
  "has_more": true,
  "next_cursor": "ver_01JBX7H2C9D4E5F6G7H8J9K0LM"
}

When has_more is false, next_cursor is null.

Purge inputs

DELETE /v1/results/{id}/inputs

Permanently deletes the stored raw inputs (name, DOB, address, phone, email, document fields, context) for a result. The decision, signals and audit log stay. Returns the result with inputs_purged_at set.

curl -X DELETE https://api.idverf.com/v1/results/ver_01JBX9Q4M2T7K8R3W5Z6N0P1QA/inputs \
  -H "Authorization: Bearer sk_test_your_key_here"

Policies

GET /v1/policies List policies (built-ins and yours)

POST /v1/policies Create a policy

GET /v1/policies/{id} Retrieve (id or built-in name)

PUT /v1/policies/{id} Update → new version

DELETE /v1/policies/{id} Delete or archive

FieldTypeNotes
namestringRequired on create. Unique per account; versions are referenced as name@n.
checksstring[]Check groups to run: identity, contact, location, document, biometrics (biometrics only produces results in capture sessions).
hard_failstring[]Reason codes that force FAIL regardless of score.
review_ifstring[]Reason codes that cap the decision at REVIEW.
pass_scoreint0–100. Score at or above this passes (absent overrides).
fail_scoreint0–100. Score below this fails. Must be below pass_score; in between is REVIEW.
on_source_errorenumREVIEW (a source ERROR forces REVIEW) or IGNORE.
min_ageintOptional, 0–125. Adds AGE_BELOW_MINIMUM when the document holder is younger.
  • Every PUT creates a new version (marketplace-sellers@2, @3…). Each verification records the version it ran under.
  • Built-ins basic, standard, strict and international are read-only; PUT/DELETE on them returns 403 builtin_policy. Their names are reserved.
  • Names are 1–64 characters (letters, digits, dash, underscore) and unique per account. Archived policies can't be updated (409 invalid_state).
  • fail_score must be lower than pass_score; unknown groups or reason codes return 400 invalid_value.
  • DELETE deletes a policy that has never been used and returns {"id": "...", "object": "policy", "deleted": true}. A policy that has been used is archived instead: it can't be used for new verifications, history keeps its versions, and the response is the policy object with "archived": true, "deleted": false. Once data retention has removed every result that used an archived policy, DELETE it again to remove it for good.
  • Saving a policy that requires checks (or reason codes) your account isn't entitled to returns 403 entitlement_required.
  • Unknown policy ids return 404 policy_not_found. Referencing an unknown or archived policy in a verification returns 400 invalid_value with param: "policy".

Create a policy

curl https://api.idverf.com/v1/policies \
  -H "Authorization: Bearer sk_test_your_key_here" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 61f0b8d2-3a9c-4e57-b1d4-8c2e7f0a9b53" \
  -d '{
  "name": "marketplace-sellers",
  "checks": ["identity", "contact", "location", "document"],
  "hard_fail": ["DECEASED", "DOCUMENT_EXPIRED", "BARCODE_FRONT_MISMATCH", "NAME_NO_MATCH"],
  "review_if": ["PHONE_OWNER_NO_MATCH", "PHONE_RECENT_PORT", "IP_ANONYMOUS", "THIN_FILE"],
  "pass_score": 75,
  "fail_score": 30,
  "on_source_error": "REVIEW"
}'

The policy object

{
  "id": "pol_01JC1D4F6H8K0M2P4R6T8V0X2Z",
  "name": "marketplace-sellers",
  "version": 1,
  "ref": "marketplace-sellers@1",
  "builtin": false,
  "archived": false,
  "definition": {
    "checks": ["identity", "contact", "location", "document"],
    "hard_fail": ["DECEASED", "DOCUMENT_EXPIRED", "BARCODE_FRONT_MISMATCH", "NAME_NO_MATCH"],
    "review_if": ["PHONE_OWNER_NO_MATCH", "PHONE_RECENT_PORT", "IP_ANONYMOUS", "THIN_FILE"],
    "pass_score": 75,
    "fail_score": 30,
    "on_source_error": "REVIEW"
  },
  "created_at": "2026-10-29T19:02:44Z",
  "updated_at": "2026-10-29T19:02:44Z"
}

GET /policies returns { "object": "list", "data": [ policy, ... ] }. Use the policy in a verification with "policy": "pol_..." or "policy": "marketplace-sellers".

List checks

GET /v1/checks

Returns the check catalog with your tier, approved purposes, entitlement for each check, and your price for each product (full and data). Prices are 0 for test keys.

{
  "object": "list",
  "tier": "open",
  "data": [
    { "key": "contact.phone_carrier", "group": "contact",
      "fields": ["phone_type", "phone_carrier", "phone_ported_days"],
      "needs": "phone", "tier": "open", "entitled": true },
    { "key": "contact.phone_owner", "group": "contact",
      "fields": ["phone_owner"], "needs": "name + phone", "tier": "vetted", "entitled": false }
  ],
  "prices": [
    { "key": "full", "name": "Full verification", "unit_amount_cents": 95, "currency": "usd" },
    { "key": "data", "name": "Data verification", "unit_amount_cents": 50, "currency": "usd" }
  ]
}

Webhook endpoints

GET /v1/webhooks List endpoints

POST /v1/webhooks Register an endpoint

DELETE /v1/webhooks/{id} Remove an endpoint

Register an HTTPS URL and the events it should receive. The response includes the signing secret (whsec_...) only on creation. Store it somewhere safe. Endpoints are per mode, so test keys register test endpoints.

curl https://api.idverf.com/v1/webhooks \
  -H "Authorization: Bearer sk_test_your_key_here" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: a3e7c1b9-6d2f-4805-9b3e-1c7f5d0a2e48" \
  -d '{
  "url": "https://example.com/webhooks/idverf",
  "events": ["verification.completed", "verification.review", "verification.expired", "session.completed"],
  "description": "Production review queue"
}'
{
  "id": "whk_01JC2E5G7J9L1N3Q5S7U9W1Y3A",
  "url": "https://example.com/webhooks/idverf",
  "events": ["verification.completed", "verification.review", "verification.expired", "session.completed"],
  "description": "Production review queue",
  "livemode": false,
  "secret": "whsec_6Jx2Q9...returned_only_once",
  "created_at": "2026-10-29T19:10:00Z"
}

Unknown endpoint ids return 404 webhook_not_found. You can also manage endpoints, rotate secrets, send test events and replay deliveries in the portal.

Usage

GET /v1/usage?from=YYYY-MM-DD&to=YYYY-MM-DD

Billable usage by product for the key's mode over an inclusive date range (UTC). check is the price key.

{
  "object": "usage",
  "from": "2026-10-01",
  "to": "2026-10-29",
  "livemode": true,
  "data": [
    { "check": "full",    "units": 2, "amount_cents": 190 },
    { "check": "data",    "units": 3, "amount_cents": 150 }
  ],
  "total_units": 5,
  "total_amount_cents": 340
}

Reference

Check catalog

Every output field, grouped as it appears under checks, with the inputs it needs and the tier it requires. If inputs or entitlement are missing, the field is NOT_CHECKED. The summary score and decision are available on every tier.

openany verified account vetteduse case reviewed credentialedenhanced review + GLBA purpose

Identity checks.identity

FieldMeaningNeedsTier
name Signal. Supplied first/last name compared with the identity record. subject name + address vetted
address Signal. Supplied address compared with the identity record. subject name + address vetted
given_address Signal. Full checks only, when you send an address. The address you sent compared with the identity record. Shows whether the person gave you a true address. If it matches the license, this equals address. If it differs, it is checked on its own: NO_MATCH adds GIVEN_ADDRESS_NO_MATCH, a past address or partial match adds GIVEN_ADDRESS_PARTIAL. subject name + address vetted
dob Signal. Supplied date of birth compared with the identity record (PARTIAL = e.g. year off by one). subject.dob vetted
deceased Boolean. true when the identity record carries a deceased indicator. name + address vetted
data_fullness Number 0–1. How completely the identity record is populated; low values indicate a thin file. name + address vetted
residence_years Integer. Years the person has been associated with the supplied address. name + address vetted
recent_move Boolean. true when the person moved to the supplied address recently. name + address vetted
sanctions Enum. CLEAR, POSSIBLE_MATCH or NOT_CHECKED. The name screened against the US Treasury OFAC sanctions list (SDN individuals and aliases), refreshed daily and screened on our servers. A match needs every word of the first and last name in a listed name. A known birth year that differs rules it out. POSSIBLE_MATCH is a prompt for human review, not a finding. Adds SANCTIONS_POSSIBLE_MATCH (no score penalty). name (birth date narrows it) open
relative_same_name Boolean or null. true when a relative in the identity records has the same first and last name (Jr./Sr. mix-ups, family identity theft). Adds NAME_SHARED_WITH_RELATIVE. name + address vetted
lookalike_relative Boolean or null. true when a sibling with the same last name is within 10 years of age. In a Full verification, true with a face similarity under 95 adds FACE_MATCH_RELATIVE_RISK (REVIEW). name + address vetted
document_reuse Integer or null. Other verifications in your account in the last 90 days with the same ID number but a different name. Above 0 adds DOCUMENT_REUSED. document number, phone or IP open
phone_reuse Integer or null. Different names used with this phone in your account in the last 30 days. 2 or more adds PHONE_REUSED. document number, phone or IP open
ip_velocity_24h Integer or null. Verifications from this IP address in your account in the last 24 hours. 5 or more adds IP_VELOCITY. Repeat-use checks only look within your own account, and we keep only keyed hashes of the values. document number, phone or IP open

Contact checks.contact

FieldMeaningNeedsTier
phone_owner Signal. Whether the phone number is registered to the named person. name + phone vetted
phone_primary Boolean or null. true when the phone is the top-ranked number on the person's identity record. Adds a little to the score. name + phone vetted
phone_type Enum. Line type, e.g. MOBILE, LANDLINE, VOIP. phone open
phone_carrier String. Name of the carrier currently serving the number. phone open
phone_ported_days Integer or null. Days since the number was last ported to a new carrier. phone open
phone_in_service Boolean. Whether the number is currently in service. phone open
email_owner Signal. Whether the email address is associated with the named person. name + email vetted
email_valid Boolean. Whether the address is syntactically valid and deliverable. email open
email_free Boolean. true for free webmail providers. email open
email_disposable Boolean. true for disposable / temporary email providers. email open
email_domain_age_days Integer or null. Days since the email's domain was registered, from the public domain registry. Custom domains only; null for free webmail like Gmail. Under 30 days adds EMAIL_DOMAIN_NEW. email open
otp Signal. MATCH after a correct one-time code, NO_MATCH after a failed one, NOT_CHECKED if no code was entered. Full verification only. phone (Full only) open

Location checks.location

FieldMeaningNeedsTier
address_components Object of signals for street_number, street, city, state, zip, zip4 and county. subject.address open
address_valid Boolean. Whether the supplied address is a valid, deliverable postal address. subject.address open
address_components Object of signals for street_number, street, city, state, zip, zip4 and county. (Comparison against the identity record.) name + subject.address vetted
address_type Enum. e.g. RESIDENTIAL or COMMERCIAL. subject.address vetted
homeowner_match Signal. Whether the named person matches the property owner of the address. name + address vetted
ip_distance_mi Integer. Miles between the IP's location and the supplied address. context.ip (context.timezone for timezone_match) open
ip_anonymous Boolean. true for proxies, VPNs and Tor exit nodes. context.ip (context.timezone for timezone_match) open
ip_threat Boolean. true when the IP is associated with abuse or attacks. context.ip (context.timezone for timezone_match) open
ip_mobile Boolean. true when the IP belongs to a mobile carrier network. context.ip (context.timezone for timezone_match) open
ip_datacenter Boolean or null. true when the IP belongs to a hosting or cloud network rather than a home or mobile connection. Privacy relays like iCloud Private Relay are not counted. Adds IP_DATACENTER. context.ip (context.timezone for timezone_match) open
ip_carrier_match Signal. MATCH, NO_MATCH or NOT_CHECKED. When the person is on mobile data, whether the network's carrier matches the phone number's carrier. MATCH adds to the score; NO_MATCH adds IP_CARRIER_MISMATCH (small penalty). context.ip (context.timezone for timezone_match) open
timezone_match Boolean or null. The device clock's time zone compared with the IP address's. A gap of an hour or more adds TIMEZONE_MISMATCH. Full verification reports the device time zone automatically; for data checks send context.timezone. context.ip (context.timezone for timezone_match) open
geo_distance_mi Integer. Miles between the device geolocation and the supplied address. context.geolocation open
geo_accuracy_m Integer. Accuracy radius reported by the device, in meters (echoed from context). context.geolocation open
geo_permission Enum. granted, denied or unavailable (echoed from context). context.geolocation open

Document checks.document

FieldMeaningNeedsTier
barcode_valid Boolean. PDF417 payload passes AAMVA structure checks: header, issuer ID vs state, version vs issue date, required fields. document.barcode_raw open
barcode_front_match Signal. Barcode data compared with the card-front fields you supplied. document.barcode_raw + document/subject fields open
number_format Signal. Document number fits the issuing state's format rules. document.number + issuing_state open
number_encodes_name_dob Signal. For states whose license numbers encode name/DOB, whether the encoding agrees. document.number + issuing_state open
mrz_valid Boolean. MRZ check digits and expiry pass (ICAO 9303). Set for passports and ID cards in Full verification. document.mrz open
mrz_front_match Signal. MRZ data compared with the document and subject fields you supplied. document.mrz open
expired Boolean. Document expiry date is in the past. document dates open
years_since_issue Integer. Whole years since the document was issued. document dates open
holder_age Integer. Holder's current age, from the supplied dates. document dates open
holder_age_at_issue Integer. Holder's age when the document was issued. document dates open
real_id Enum. REAL ID compliance flag from the barcode, e.g. COMPLIANT or NON_COMPLIANT. document.barcode_raw open

Biometrics checks.biometrics

FieldMeaningNeedsTier
liveness Enum. PASS when the real-time selfie check found a live person present, otherwise FAIL. capture session selfie open
liveness_confidence Number 0–100. Confidence of the liveness check. capture session selfie open
liveness_method Enum. light (face movement plus a short series of colored light flashes, the stronger test) or movement (face movement only). We start with light. If a light attempt can't finish (bright sun, timeout, camera trouble), later attempts use movement and LIVENESS_MOVEMENT_ONLY is added (a small penalty). A light attempt that finishes with a low score is retried with light. capture session selfie open
face_match Signal. MATCH or NO_MATCH comparing the selfie with the photo on the ID front; NOT_CHECKED if either face is missing. capture session selfie + ID front open
face_similarity Number 0–100 or null. Similarity between the selfie and the ID photo. capture session selfie + ID front open
document_face_detected Boolean. Whether a face was found on the ID front. capture session selfie + ID front open
age_estimate Text like "33-43", or null. The age range the selfie appears to be. Estimated on the fly; nothing is stored. capture session selfie + ID front open
age_consistent Boolean or null. Whether the age on the ID fits the selfie's estimated age (with a 12-year margin). False adds AGE_ESTIMATE_MISMATCH (REVIEW). capture session selfie + ID front open
selfie_faces Number or null. Faces in the selfie. More than one adds SELFIE_MULTIPLE_FACES (REVIEW). capture session selfie + ID front open
selfie_sunglasses Boolean or null. Sunglasses in the selfie. True adds SELFIE_SUNGLASSES (REVIEW). capture session selfie + ID front open
id_type Enum. The ID the person chose: drivers_license (a driver's license or state ID), passport, or id_card (another ID card with machine-readable lines on the back). capture session ID front + back open
document_front_readable Boolean. Whether the text on the ID front could be read. capture session ID front + back open
barcode_read Boolean. Whether the PDF417 barcode on the back of a license was read. null for passports and ID cards. capture session ID front + back open
mrz_read Boolean. Whether the MRZ (the machine-readable lines on a passport photo page or on the back of an ID card) was read. null for licenses. capture session ID front + back open
id_name_match Signal. MATCH, PARTIAL, NO_MATCH or NOT_CHECKED. The first and last name you sent compared with the name on the ID. NO_MATCH adds ID_NAME_MISMATCH (REVIEW). capture session ID front + back open
id_middle_name_match Signal. MATCH, NO_MATCH or NOT_CHECKED. The optional middle_name you sent compared with the middle name on the ID (an initial matches). NOT_CHECKED if you didn't send one or the ID has none. NO_MATCH adds ID_MIDDLE_NAME_MISMATCH. capture session ID front + back open
id_address_match Signal. MATCH, PARTIAL, NO_MATCH or NOT_CHECKED. The optional address you sent compared with the address on a driver's license or state ID. NOT_CHECKED for passports and ID cards (they have no address). NO_MATCH adds ID_ADDRESS_MISMATCH (a small penalty; people move). capture session ID front + back open
document_sharpness Number 0-100 or null. How sharp the ID front photo is. A very blurry photo is retaken (up to 3 tries), then accepted with DOCUMENT_BLURRY (REVIEW). capture session ID front + back open
document_on_screen Boolean or null. The ID photo looks like a picture of a screen (a phone, tablet or monitor filling the photo) instead of the real card. True adds DOCUMENT_ON_SCREEN (REVIEW). capture session ID front + back open

Postal validation of address_components is open tier; comparing them with the identity record requires vetted. Open-tier accounts still get a decision based on contact, IP and document checks.

Reason codes

Returned in reasons[] (most severe first) and used in policy hard_fail / review_if lists. New codes may be added. Make sure your code handles unknown ones.

CodeMeaning
DECEASEDIdentity record carries a deceased indicator
NAME_NO_MATCHName does not match the identity record
NAME_NOT_FOUNDNo identity record found for this name and address
ADDRESS_NO_MATCHAddress does not match the identity record
ADDRESS_PARTIALAddress only partly matches the identity record
GIVEN_ADDRESS_NO_MATCHThe address you provided (different from the one on the ID) does not match the identity record
GIVEN_ADDRESS_PARTIALThe address you provided (different from the one on the ID) only partly matches the identity record, or is a past address
DOB_NO_MATCHDate of birth does not match the identity record
DOB_PARTIALDate of birth only partly matches
THIN_FILEIdentity record is sparsely populated
RECENT_MOVESubject moved to this address recently
PHONE_OWNER_NO_MATCHPhone is not registered to this person
PHONE_NOT_IN_SERVICEPhone number is not in service
PHONE_VOIPPhone is a VoIP line
PHONE_RECENT_PORTPhone was ported to a new carrier recently
EMAIL_DOMAIN_NEWThe email's domain was registered in the last 30 days
PHONE_REUSEDThis phone number was used with other names in recent verifications
EMAIL_OWNER_NO_MATCHEmail is associated with a different person
EMAIL_INVALIDEmail address is not deliverable
EMAIL_DISPOSABLEEmail address is from a disposable provider
OTP_FAILEDOne-time passcode was not confirmed
ADDRESS_INVALIDAddress is not a valid postal address
ADDRESS_COMPONENT_MISMATCHSome address components do not match
ADDRESS_COMMERCIALAddress is a business address
HOMEOWNER_NO_MATCHProperty owner is a different person
IP_ANONYMOUSIP is a proxy, VPN or Tor exit
IP_THREATIP is associated with abuse or attacks
IP_DATACENTERIP address belongs to a hosting or cloud network, not a home or mobile connection
IP_CARRIER_MISMATCHOn mobile data, but the network carrier differs from the phone number's carrier
TIMEZONE_MISMATCHThe device clock's time zone differs from the IP address's
IP_VELOCITYMany verifications from this IP address in the last 24 hours
IP_DISTANCE_HIGHIP location is far from the address
GEO_DISTANCE_HIGHDevice location is far from the address
GEO_PERMISSION_DENIEDUser declined to share device location
BARCODE_INVALIDBarcode payload fails AAMVA structure checks
BARCODE_FRONT_MISMATCHBarcode data disagrees with the card front
DOCUMENT_NUMBER_INVALIDDocument number does not fit the issuer format
DOCUMENT_NUMBER_ENCODING_MISMATCHLicense number does not encode the holder name/DOB
MRZ_INVALIDMRZ check digits fail
MRZ_FRONT_MISMATCHMRZ data disagrees with the document fields
DOCUMENT_EXPIREDDocument is expired
DOCUMENT_DATES_INVALIDDocument dates are impossible (e.g. issued before birth)
AGE_BELOW_MINIMUMHolder is younger than the policy minimum age
REAL_ID_NON_COMPLIANTDocument is not REAL ID compliant
LIVENESS_FAILEDSelfie did not pass the liveness check
ID_NAME_MISMATCHThe name on the ID does not match the name provided
ID_MIDDLE_NAME_MISMATCHThe middle name on the ID does not match the middle name provided
ID_ADDRESS_MISMATCHThe address on the ID does not match the address provided (the person may have moved)
SANCTIONS_POSSIBLE_MATCHName (and birth year, if known) matches an entry on the US sanctions list; review before proceeding
NAME_SHARED_WITH_RELATIVEA relative has the same name (Jr./Sr.); check the birth date carefully
FACE_MATCH_RELATIVE_RISKA look-alike relative exists and the face match was not strong enough to rule them out
DOCUMENT_REUSEDThis ID number was used with a different name in another verification
LIVENESS_MOVEMENT_ONLYThe light test could not finish, so the movement-only liveness test was used
LIVENESS_LOWLiveness confidence was low (between the review and pass levels)
FACE_NO_MATCHSelfie does not match the photo on the ID
DOCUMENT_FACE_NOT_FOUNDNo face could be found on the ID front
AGE_ESTIMATE_MISMATCHThe selfie looks much older or younger than the birth date on the ID
SELFIE_MULTIPLE_FACESMore than one face was in the selfie
SELFIE_SUNGLASSESThe person wore sunglasses in the selfie
DOCUMENT_ON_SCREENThe ID photo looks like a picture of a screen, not the real card
DOCUMENT_BLURRYThe ID photo was too blurry to check well
DOCUMENT_FRONT_PARTIALOne detail from the barcode or code lines could not be found in the printed text on the ID
DOCUMENT_FRONT_UNREADABLEText on the ID front could not be read
MRZ_UNREADABLEThe machine-readable lines on the passport could not be read
BARCODE_UNREADABLEThe barcode on the back of the ID could not be read
SOURCE_ERRORA data source was unavailable; affected signals are ERROR

Built-in policies

Read-only policies you can use as a starting point. Use them by name ("policy": "standard") or copy one into your own policy. Use international for people outside the US.

basic

pass ≥ 60 · fail < 25
Checks
contactlocationdocument
Hard fail
DOCUMENT_EXPIREDBARCODE_FRONT_MISMATCHMRZ_FRONT_MISMATCH
Review if
IP_THREATEMAIL_DISPOSABLEPHONE_NOT_IN_SERVICEIP_DATACENTER
On source error
IGNORE

standard

pass ≥ 75 · fail < 30
Checks
identitycontactlocationdocument
Hard fail
DECEASEDDOCUMENT_EXPIREDBARCODE_FRONT_MISMATCHNAME_NO_MATCH
Review if
PHONE_OWNER_NO_MATCHPHONE_RECENT_PORTIP_ANONYMOUSTHIN_FILEOTP_FAILEDIP_DATACENTEREMAIL_DOMAIN_NEWSANCTIONS_POSSIBLE_MATCHNAME_SHARED_WITH_RELATIVEDOCUMENT_REUSEDPHONE_REUSED
On source error
REVIEW

strict

pass ≥ 85 · fail < 45
Checks
identitycontactlocationdocument
Hard fail
DECEASEDNAME_NO_MATCHDOB_NO_MATCHDOCUMENT_EXPIREDDOCUMENT_DATES_INVALIDBARCODE_INVALIDBARCODE_FRONT_MISMATCHMRZ_INVALIDMRZ_FRONT_MISMATCHIP_THREATOTP_FAILED
Review if
PHONE_OWNER_NO_MATCHPHONE_RECENT_PORTPHONE_VOIPIP_ANONYMOUSTHIN_FILEADDRESS_NO_MATCHEMAIL_DISPOSABLEEMAIL_OWNER_NO_MATCHGEO_DISTANCE_HIGHIP_DISTANCE_HIGHDOCUMENT_NUMBER_ENCODING_MISMATCHDOCUMENT_NUMBER_INVALIDIP_DATACENTEREMAIL_DOMAIN_NEWSANCTIONS_POSSIBLE_MATCHNAME_SHARED_WITH_RELATIVEDOCUMENT_REUSEDPHONE_REUSEDTIMEZONE_MISMATCHIP_CARRIER_MISMATCHIP_VELOCITY
On source error
REVIEW

international

pass ≥ 70 · fail < 35
Checks
identitycontactlocationdocument
Hard fail
DECEASEDDOCUMENT_EXPIREDDOCUMENT_DATES_INVALIDMRZ_INVALIDMRZ_FRONT_MISMATCHBARCODE_FRONT_MISMATCH
Review if
IP_THREATIP_ANONYMOUSIP_DATACENTEREMAIL_DISPOSABLEEMAIL_DOMAIN_NEWSANCTIONS_POSSIBLE_MATCHDOCUMENT_REUSEDPHONE_REUSEDTIMEZONE_MISMATCHNAME_SHARED_WITH_RELATIVE
On source error
REVIEW

Webhooks & signatures

EventWhen
verification.completedAn async verification finished
verification.reviewDecision is REVIEW (for review queues)
verification.reviewedSomeone on your team approved or rejected a REVIEW result
verification.expiredA capture session timed out before it was finished
session.startedThe person opened a capture session link
session.completedA capture session finished and its verification has a decision
session.expiredA capture session link expired before it was finished

Payload

IDVerf sends a POST with a JSON body. data is the full result object. For session.* events, data.session also carries the session object. verification.expired also fires when a capture link expires. Respond with any 2xx within a few seconds, and do slow work in the background. Deduplicate on the event id.

POST /webhooks/idverf HTTP/1.1
Content-Type: application/json
IDVerf-Signature: t=1761763263,v1=5f2b9c0e7a1d4f63b8e2c9a07d5e1f3b6a8c0d2e4f6a8b0c2d4e6f8a0b2c4d6e

{
  "id": "evt_01JC3F6H8K0M2P4R6T8V0X2Z4B",
  "type": "verification.review",
  "created_at": "2026-10-29T18:41:03Z",
  "data": { "id": "ver_01JBX9Q4M2T7K8R3W5Z6N0P1QA", "status": "completed", "decision": "REVIEW", "...": "..." }
}

Verifying signatures

Every delivery carries:

IDVerf-Signature: t=<unix timestamp>,v1=<hex HMAC-SHA256(secret, "<t>.<raw body>")>
  1. Split the header on , and read t and v1.
  2. Compute HMAC-SHA256 of t + "." + raw request body using your endpoint's whsec_ secret, hex-encoded.
  3. Compare with v1 using a constant-time comparison.
  4. Reject the request if t is more than 5 minutes from your clock.

Use the raw body bytes. Re-serialized JSON won't match.

<?php
function idverf_verify_signature(string $payload, string $header, string $secret, int $tolerance = 300): bool
{
    $parts = [];
    foreach (explode(',', $header) as $pair) {
        [$k, $v] = array_pad(explode('=', trim($pair), 2), 2, '');
        $parts[$k] = $v;
    }
    if (empty($parts['t']) || empty($parts['v1'])) {
        return false;
    }
    if (abs(time() - (int) $parts['t']) > $tolerance) {
        return false; // too old (or clock skew)
    }
    $expected = hash_hmac('sha256', $parts['t'] . '.' . $payload, $secret);
    return hash_equals($expected, $parts['v1']);
}

$payload = file_get_contents('php://input');   // raw body
$header  = $_SERVER['HTTP_IDVERF_SIGNATURE'] ?? '';
if (! idverf_verify_signature($payload, $header, getenv('IDVERF_WEBHOOK_SECRET'))) {
    http_response_code(400);
    exit;
}
$event = json_decode($payload, true);
// handle $event['type'] / $event['data'] ...
http_response_code(200);
const crypto = require('crypto');
const express = require('express');

function verifyIdverfSignature(rawBody, header, secret, toleranceSec = 300) {
  const parts = {};
  for (const pair of header.split(',')) {
    const i = pair.indexOf('=');
    if (i > 0) parts[pair.slice(0, i).trim()] = pair.slice(i + 1).trim();
  }
  const t = Number(parts.t);
  if (!t || !parts.v1) return false;
  if (Math.abs(Date.now() / 1000 - t) > toleranceSec) return false;

  const expected = crypto.createHmac('sha256', secret).update(`${t}.${rawBody}`).digest('hex');
  const a = Buffer.from(expected, 'hex');
  const b = Buffer.from(parts.v1, 'hex');
  return a.length === b.length && crypto.timingSafeEqual(a, b);
}

const app = express();
app.post('/webhooks/idverf', express.raw({ type: 'application/json' }), (req, res) => {
  const raw = req.body.toString('utf8');
  if (!verifyIdverfSignature(raw, req.get('IDVerf-Signature') || '', process.env.IDVERF_WEBHOOK_SECRET)) {
    return res.sendStatus(400);
  }
  const event = JSON.parse(raw);
  // handle event.type / event.data ...
  res.sendStatus(200);
});
import hashlib
import hmac
import os
import time

def verify_idverf_signature(raw_body: bytes, header: str, secret: str, tolerance: int = 300) -> bool:
    parts = dict(p.strip().split("=", 1) for p in header.split(",") if "=" in p)
    try:
        t = int(parts["t"])
    except (KeyError, ValueError):
        return False
    if abs(time.time() - t) > tolerance:
        return False
    signed = f"{t}.".encode() + raw_body
    expected = hmac.new(secret.encode(), signed, hashlib.sha256).hexdigest()
    return hmac.compare_digest(expected, parts.get("v1", ""))

# Flask example
from flask import Flask, request, abort
app = Flask(__name__)

@app.post("/webhooks/idverf")
def idverf_webhook():
    if not verify_idverf_signature(request.get_data(), request.headers.get("IDVerf-Signature", ""),
                                   os.environ["IDVERF_WEBHOOK_SECRET"]):
        abort(400)
    event = request.get_json()
    # handle event["type"] / event["data"] ...
    return "", 200

Retries

Any non-2xx response or timeout is retried with exponential backoff for up to 24 hours. Deliveries may arrive more than once or out of order. Deduplicate on id and, if needed, fetch the latest state with GET /results/{id}. Delivery logs and manual retries are in the portal.

Compliance notes

  • Purpose and consent are required on every data check (and purpose on every Full verification). Both are stored with the audit record. Get the end user's consent before you call, and send when (consent.obtained_at) and which text version (consent.version).
  • Purposes outside your account's approved list return 403 purpose_not_permitted.
  • Not FCRA. IDVerf is not a consumer reporting agency. Don't use results to decide eligibility for credit, employment, housing or insurance; purpose has no such values.
  • IDVerf does not check Social Security numbers. Never send one: subject.ssn is rejected with 400 invalid_value.
  • Raw inputs are encrypted at rest and purged after 90 days by default (configurable down to 0). Results and audit metadata are kept 5 years. Purge on demand with DELETE /results/{id}/inputs.
  • Biometrics. IDVerf shows the person a biometric consent notice and records their agreement before any selfie or ID photo is captured. Photos are encrypted and kept for your image retention setting (0–7 days, default 3), then deleted; face measurements are used only for the comparison and not stored. See the Biometric Privacy Notice. Treat photos you view in the portal as sensitive. Don't download them or keep them after your review.

More on our Security & compliance page and in the Terms and Acceptable Use Policy.

What's next

Hosted capture sessions, liveness and face match are live now. Next, we plan an embeddable capture SDK using pk_ keys, and direct image upload if you have your own camera UI. These will add fields and enum values to the same verification resource. v1 integrations will keep working unchanged, as long as you ignore unknown fields and enum values.

Start building

Get a free sandbox key and try the magic values.

Questions about the API? Contact support.