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"
| Prefix | Use |
|---|---|
| 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.
| Prefix | Object |
|---|---|
| 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:
| Header | Meaning |
|---|---|
| X-RateLimit-Limit | Requests allowed in the current window |
| X-RateLimit-Remaining | Requests left in the current window |
| X-RateLimit-Reset | Unix time when the window resets |
| Retry-After | On 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"
}
}
| HTTP | type | code | When |
|---|---|---|---|
| 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. |
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).
| product | Start with | What runs | Billed |
|---|---|---|---|
| full | POST /full | One-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) |
| data | POST /data | Data 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
| status | Meaning |
|---|---|
| processing | Checks running (async requests only). |
| awaiting_input | Full only: waiting for the person to finish the hosted capture page. |
| completed | Decision is final for the current inputs. |
| expired | A capture link wasn't finished within 24 hours (refunded, no decision). |
| failed | Could 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:
| Value | Meaning |
|---|---|
| MATCH | Input agrees with the source. |
| PARTIAL | Partly agrees (e.g. DOB year ±1, street only). |
| NO_MATCH | The source has the person, but the input disagrees. |
| NOT_FOUND | The source has no record to compare. |
| NOT_CHECKED | Input missing, check not in the policy, or not entitled. |
| ERROR | The 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.
Request body
| Field | Type | Required | Notes |
|---|---|---|---|
| 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. |
| 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
| Field | Type | Notes |
|---|---|---|
| id | string | ses_... |
| object | string | session |
| type | enum | Always full. |
| status | enum | created (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). |
| url | string | The one-time capture link. Returned only in the create response; null when you get or list sessions. |
| verification_id | string | The id of the result (ver_...). Fetch it from GET /results/{id} for the check-level result. |
| steps | object | consent, 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, reasons | mixed | Copied from the result once completed; null / [] before. |
| reference_id | string | Echoed. |
| livemode | boolean | true for sk_live_ keys. |
| created_at, expires_at, completed_at | timestamp | |
| images_deleted_at | timestamp | When the photos were deleted under your image retention setting. |
The hosted capture flow
What the person sees at the url:
- Consent. They read the biometric consent notice and tap I agree. Nothing is captured before this. The agreement is recorded with the session.
- 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.
- Liveness selfie. A short real-time check confirms a live person is there.
- 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.
- 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).
- 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.
- 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.
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.
Request body
| Field | Type | Required | Notes |
|---|---|---|---|
| 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.
| Field | Type | Notes |
|---|---|---|
| id | string | ver_... |
| object | string | verification |
| product | enum | full or data. See Products. |
| session_id | string | ses_... for Full verifications; otherwise null. |
| status | enum | processing, awaiting_input (Full only), completed, expired, failed. See Statuses. |
| decision | enum | PASS, REVIEW, FAIL; null while processing. |
| score | int | 0–100, higher = more likely genuine. |
| policy | string | Policy applied, with its version, e.g. standard@3. |
| reasons | string[] | Reason codes, most severe first. |
| checks | object | Grouped results: identity, contact, location, document, biometrics. See Check catalog. |
| inputs_present | string[] | Which input blocks were supplied (no values). |
| reference_id | string | Echoed. |
| purpose | string | Echoed. |
| livemode | boolean | true for sk_live_ keys, false for sk_test_. |
| created_at | timestamp | |
| completed_at | timestamp | null while processing. |
| inputs_purged_at | timestamp | When stored inputs were purged (retention or DELETE); otherwise null. |
| otp | object | Full 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_at | timestamp | When capture photos were deleted under your image retention setting; otherwise null. |
| review | object | Set 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. |
| billing | object | units (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 param | Notes |
|---|---|
| reference_id | Exact match on your reference id. |
| created_after | ISO 8601 timestamp. Only results created after it. |
| created_before | ISO 8601 timestamp. Only results created before it. |
| decision | PASS, REVIEW or FAIL. |
| product | full or data. |
| status | processing, awaiting_input, completed, expired or failed. |
| limit | 1–100, default 20. |
| starting_after | A 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
| Field | Type | Notes |
|---|---|---|
| name | string | Required on create. Unique per account; versions are referenced as name@n. |
| checks | string[] | Check groups to run: identity, contact, location, document, biometrics (biometrics only produces results in capture sessions). |
| hard_fail | string[] | Reason codes that force FAIL regardless of score. |
| review_if | string[] | Reason codes that cap the decision at REVIEW. |
| pass_score | int | 0–100. Score at or above this passes (absent overrides). |
| fail_score | int | 0–100. Score below this fails. Must be below pass_score; in between is REVIEW. |
| on_source_error | enum | REVIEW (a source ERROR forces REVIEW) or IGNORE. |
| min_age | int | Optional, 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.
Identity checks.identity
| Field | Meaning | Needs | Tier |
|---|---|---|---|
| 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
| Field | Meaning | Needs | Tier |
|---|---|---|---|
| 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. | open | |
| email_free | Boolean. true for free webmail providers. | open | |
| email_disposable | Boolean. true for disposable / temporary email providers. | 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. | 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
| Field | Meaning | Needs | Tier |
|---|---|---|---|
| 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
| Field | Meaning | Needs | Tier |
|---|---|---|---|
| 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
| Field | Meaning | Needs | Tier |
|---|---|---|---|
| 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.
| Code | Meaning |
|---|---|
| DECEASED | Identity record carries a deceased indicator |
| NAME_NO_MATCH | Name does not match the identity record |
| NAME_NOT_FOUND | No identity record found for this name and address |
| ADDRESS_NO_MATCH | Address does not match the identity record |
| ADDRESS_PARTIAL | Address only partly matches the identity record |
| GIVEN_ADDRESS_NO_MATCH | The address you provided (different from the one on the ID) does not match the identity record |
| GIVEN_ADDRESS_PARTIAL | The address you provided (different from the one on the ID) only partly matches the identity record, or is a past address |
| DOB_NO_MATCH | Date of birth does not match the identity record |
| DOB_PARTIAL | Date of birth only partly matches |
| THIN_FILE | Identity record is sparsely populated |
| RECENT_MOVE | Subject moved to this address recently |
| PHONE_OWNER_NO_MATCH | Phone is not registered to this person |
| PHONE_NOT_IN_SERVICE | Phone number is not in service |
| PHONE_VOIP | Phone is a VoIP line |
| PHONE_RECENT_PORT | Phone was ported to a new carrier recently |
| EMAIL_DOMAIN_NEW | The email's domain was registered in the last 30 days |
| PHONE_REUSED | This phone number was used with other names in recent verifications |
| EMAIL_OWNER_NO_MATCH | Email is associated with a different person |
| EMAIL_INVALID | Email address is not deliverable |
| EMAIL_DISPOSABLE | Email address is from a disposable provider |
| OTP_FAILED | One-time passcode was not confirmed |
| ADDRESS_INVALID | Address is not a valid postal address |
| ADDRESS_COMPONENT_MISMATCH | Some address components do not match |
| ADDRESS_COMMERCIAL | Address is a business address |
| HOMEOWNER_NO_MATCH | Property owner is a different person |
| IP_ANONYMOUS | IP is a proxy, VPN or Tor exit |
| IP_THREAT | IP is associated with abuse or attacks |
| IP_DATACENTER | IP address belongs to a hosting or cloud network, not a home or mobile connection |
| IP_CARRIER_MISMATCH | On mobile data, but the network carrier differs from the phone number's carrier |
| TIMEZONE_MISMATCH | The device clock's time zone differs from the IP address's |
| IP_VELOCITY | Many verifications from this IP address in the last 24 hours |
| IP_DISTANCE_HIGH | IP location is far from the address |
| GEO_DISTANCE_HIGH | Device location is far from the address |
| GEO_PERMISSION_DENIED | User declined to share device location |
| BARCODE_INVALID | Barcode payload fails AAMVA structure checks |
| BARCODE_FRONT_MISMATCH | Barcode data disagrees with the card front |
| DOCUMENT_NUMBER_INVALID | Document number does not fit the issuer format |
| DOCUMENT_NUMBER_ENCODING_MISMATCH | License number does not encode the holder name/DOB |
| MRZ_INVALID | MRZ check digits fail |
| MRZ_FRONT_MISMATCH | MRZ data disagrees with the document fields |
| DOCUMENT_EXPIRED | Document is expired |
| DOCUMENT_DATES_INVALID | Document dates are impossible (e.g. issued before birth) |
| AGE_BELOW_MINIMUM | Holder is younger than the policy minimum age |
| REAL_ID_NON_COMPLIANT | Document is not REAL ID compliant |
| LIVENESS_FAILED | Selfie did not pass the liveness check |
| ID_NAME_MISMATCH | The name on the ID does not match the name provided |
| ID_MIDDLE_NAME_MISMATCH | The middle name on the ID does not match the middle name provided |
| ID_ADDRESS_MISMATCH | The address on the ID does not match the address provided (the person may have moved) |
| SANCTIONS_POSSIBLE_MATCH | Name (and birth year, if known) matches an entry on the US sanctions list; review before proceeding |
| NAME_SHARED_WITH_RELATIVE | A relative has the same name (Jr./Sr.); check the birth date carefully |
| FACE_MATCH_RELATIVE_RISK | A look-alike relative exists and the face match was not strong enough to rule them out |
| DOCUMENT_REUSED | This ID number was used with a different name in another verification |
| LIVENESS_MOVEMENT_ONLY | The light test could not finish, so the movement-only liveness test was used |
| LIVENESS_LOW | Liveness confidence was low (between the review and pass levels) |
| FACE_NO_MATCH | Selfie does not match the photo on the ID |
| DOCUMENT_FACE_NOT_FOUND | No face could be found on the ID front |
| AGE_ESTIMATE_MISMATCH | The selfie looks much older or younger than the birth date on the ID |
| SELFIE_MULTIPLE_FACES | More than one face was in the selfie |
| SELFIE_SUNGLASSES | The person wore sunglasses in the selfie |
| DOCUMENT_ON_SCREEN | The ID photo looks like a picture of a screen, not the real card |
| DOCUMENT_BLURRY | The ID photo was too blurry to check well |
| DOCUMENT_FRONT_PARTIAL | One detail from the barcode or code lines could not be found in the printed text on the ID |
| DOCUMENT_FRONT_UNREADABLE | Text on the ID front could not be read |
| MRZ_UNREADABLE | The machine-readable lines on the passport could not be read |
| BARCODE_UNREADABLE | The barcode on the back of the ID could not be read |
| SOURCE_ERROR | A 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
| Event | When |
|---|---|
| verification.completed | An async verification finished |
| verification.review | Decision is REVIEW (for review queues) |
| verification.reviewed | Someone on your team approved or rejected a REVIEW result |
| verification.expired | A capture session timed out before it was finished |
| session.started | The person opened a capture session link |
| session.completed | A capture session finished and its verification has a decision |
| session.expired | A 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>")>
- Split the header on , and read t and v1.
- Compute HMAC-SHA256 of t + "." + raw request body using your endpoint's whsec_ secret, hex-encoded.
- Compare with v1 using a constant-time comparison.
- 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.