Core Concepts

Verifications & Checks

A verification check is a single step in a workflow — one unit of identity verification logic. Checks are executed by the workflow engine in the order defined by your workflow graph. Each check produces an independent pass/fail result.

Check lifecycle

pending → passed
        → failed
        → error
        → skipped
        → requires_retry
StatusDescription
passedThe check completed successfully and passed.
failedThe check completed but the subject did not pass.
errorAn unrecoverable error occurred (e.g., service unavailable).
skippedThe check was skipped because prerequisites were missing (e.g., OCR data unavailable).
pendingThe check is currently executing.
requires_retryA transient failure occurred. The engine will retry automatically (up to 4 retries).

Each check attempt is stored as an immutable record with an incrementing attempt number. Retries create new records rather than overwriting the original.

Check categories

Extraction

CheckDescription
document_ocrScans the ID document front and back images. Extracts name, date of birth, address, document number, expiration date, and other fields. Validates MRZ checksums and barcode data when present.

Biometric verification

CheckDescription
face_matchCompares the selfie against the ID photo using ArcFace face embeddings. Returns a similarity score (0.0–1.0). Configurable security levels: standard (0.35 threshold), strict (0.50), very_strict (0.60). Includes liveness validation when available.
nfc_chip_authReads and validates the NFC chip in e-passports. Performs passive and active authentication, cross-references chip data against OCR, and compares the chip photo against the selfie.

Document evaluation

CheckDescription
document_expirationRejects documents that have expired based on the extracted expiration date.
id_document_filterFilters by country and document type matrix. Reject or allow specific combinations (e.g., only accept US passports and driver’s licenses).
proof_of_address_checkValidates proof-of-address documents (utility bills, bank statements). Checks document recency and cross-references the address against extracted ID data using fuzzy matching (0.70 threshold).

Compliance screening

CheckDescription
watchlist_screeningScreens against built-in OFAC, EU, UN, and UK sanctions lists. Automatically injected into all workflows — you don’t need to add it manually.
aml_screeningEnhanced AML screening against 6,000+ global watchlists, PEP databases, and adverse media sources. Supports continuous monitoring with automatic re-screening.
email_risk_enhancedEmail risk analysis including breach history, deliverability, domain age, and fraud scoring.
phone_risk_enhancedPhone number risk analysis including SIM swap detection, porting history, VoIP detection, and carrier verification.
address_validationAddress standardization and deliverability verification. Validates against postal databases and returns geocoded coordinates.

Fraud detection

CheckDescription
duplicate_detectionSearches for the same person across all previous sessions using hashed device fingerprints, email, phone, document number, and face embeddings.
risk_assessmentAggregates 150+ fraud signals (behavioral, device, network, document forensics) into a composite risk score (0–100). Automatically injected into all workflows.
check_against_listMatches subject data against your custom allow/block/flag lists. Supports name, email, phone, IP address, device fingerprint, government ID, and geolocation matching.
identity_crossrefCross-references user-submitted data (from the capture form) against data extracted from the document. Detects mismatches in name, date of birth, and address.

Decisioning

CheckDescription
auto_approveEvaluates all prior check results. If everything passed, routes to approved. Otherwise routes to needs_review or rejected based on configuration.
external_gatePauses the workflow and waits for your server to make a decision via API callback. Useful for custom business logic or human-in-the-loop integrations. Configurable timeout (default: 24 hours).

Auto-injected checks

Some checks are automatically added to every workflow run regardless of your workflow configuration:

  • watchlist_screening — Required for compliance. Always runs.
  • risk_assessment — Required for fraud scoring. Always runs.
  • identity_crossref — Runs for certain plan tiers to detect form/document mismatches.

You cannot remove auto-injected checks, but you can configure how their results affect the workflow outcome.

Check results in the session result

After a session completes, each check’s result is available in the check_results object:

1{
2  "check_results": {
3    "document_ocr": {
4      "status": "passed",
5      "details": {
6        "fields_extracted": 12,
7        "mrz_valid": true,
8        "barcode_valid": true
9      }
10    },
11    "face_match": {
12      "status": "passed",
13      "score": 0.94,
14      "liveness_passed": true
15    },
16    "age_verification": {
17      "status": "passed",
18      "extracted_age": 28,
19      "minimum_age": 18
20    },
21    "watchlist_screening": {
22      "status": "passed",
23      "hits": 0
24    },
25    "risk_assessment": {
26      "status": "passed",
27      "risk_score": 12,
28      "risk_level": "low",
29      "triggered_signals": 2
30    }
31  }
32}

Configuring checks in workflows

Each check can be configured with parameters specific to its type. For example:

1{
2  "type": "policy",
3  "policy": "face_match",
4  "config": {
5    "security_level": "strict"
6  },
7  "on_pass": "next_step",
8  "on_fail": "review_terminal"
9}

See Workflows for how to build verification graphs with checks, conditionals, and routing logic.

Standalone checks via API

You can also run checks independently of a session through the checks API:

$curl -X POST https://api.withverifa.com/api/v1/checks \
>  -H "X-API-Key: vk_live_your_key_here" \
>  -H "Content-Type: application/json" \
>  -d '{
>    "check_type": "sanction",
>    "external_ref": "user_abc123",
>    "name_first": "Jane",
>    "name_last": "Doe",
>    "birthdate": "1997-06-15"
>  }'

This is useful for:

  • Running AML screening on existing customers
  • Adding phone or email risk checks after onboarding
  • Re-screening identities on a schedule

See the API reference for the full list of check endpoints.