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

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

Biometric verification

Document evaluation

Compliance screening

Fraud detection

Decisioning

Proof of address

proof_of_address_check is the one check with a policy of its own. Rather than a single threshold, it resolves a full proof-of-address policy and reports every finding it made along the way.

Three-state outcome

Unlike other checks, a proof-of-address result is not just pass or fail:

review deliberately surfaces as passed: false, so integrations that only read passed stay safe: they treat a borderline document as not-yet-approved rather than silently approving it. Branch on details.outcome when you want the three-way distinction.

Reasons

Every finding is collected into details.reasons — a list of {code, severity, message} objects. Severity is fail, review, or info. The check takes the worst severity present: any fail reason fails it, otherwise any review reason routes it to review, otherwise it passes.

Codes are stable — pivot your UI and metrics off code, never off message.

Presets and policy precedence

A policy is resolved from four layers, each overriding the last:

built-in defaults  ←  regional preset  ←  organization settings  ←  workflow node config

Presets (us, uk, eu, in, mx, au, ca, za, or custom) are regional starting points — the UK preset accepts council tax and rejects PO boxes, the India preset accepts mobile phone bills and address-bearing IDs. Anything a preset omits keeps the built-in default.

Organization settings live in the dashboard under Settings → Proof of address. A workflow node either says “use organization settings” — the default — or overrides individual fields for that one workflow. Node config wins wherever it sets a value; everything else falls through to the org.

The policy that actually ran is snapshotted into details.policy, so a decision stays explainable after you change the settings.

Document types and recency windows

Each accepted subtype carries its own default window — 90 days for a utility bill or bank statement, 180 for a mobile phone bill or insurance statement, 365 for council tax, tax documents, benefits letters, and mortgage statements. Override them per type in max_age_days_by_type, and per country in country_overrides — for example, utility bills issued in India are commonly held to 60 days regardless of your preset.

Three subtypes are review-only: lease_agreement, institution_letter, and other have no official issuer, so a pass on one of them still routes to a human. id_with_address is not an independent source — it shares its issuer with the ID document — and is only accepted when the policy sets id_with_address_satisfies.

Issuing country

Pass poa_issuing_country (ISO 3166-1 alpha-2) with the upload when you know it; otherwise the check falls back to the country of the ID document on the session. The issuing country drives address normalisation (postcode formats, region names versus codes, unit tokens), PO-box detection, and any per-country window override. When it disagrees with the ID document’s country, country_mismatch_action decides whether that is ignored, sent to review, or failed.

Name and address matching

Name and address are scored separately, 0.0–1.0, and each is banded against two thresholds. At or above *_match_pass the component passes; at or above *_match_review it is partial and routes to review; below that it fails. The default bands are 0.85 / 0.60 for names and 0.80 / 0.55 for addresses.

Name matching ignores titles and middle names, folds accents, understands common nicknames, and accepts any one of several joint holders printed on the document. Address matching compares components — line 1, city, region, postcode, unit — and treats a region code and its spelled-out name as equivalent.

By default the reference is the applicant’s declared address; set address_source to id_document to compare against the address extracted from the ID instead. The other source is still compared and reported under details.secondary_cross_reference — a divergence there is a fraud signal rather than a check failure. In an unguided flow (require_declared_address: false) there is no reference at all: the address is extracted, no score is produced, and address_not_compared is reported.

Example result

1
{
2
  "status": "failed",
3
  "details": {
4
    "outcome": "review",
5
    "passed": false,
6
    "action_override": "review",
7
    "reasons": [
8
      {
9
        "code": "address_partial",
10
        "severity": "review",
11
        "message": "Address matches except for the unit number."
12
      }
13
    ],
14
    "reason_code": "poa_review",
15
    "document_type": "utility_bill",
16
    "document_type_canonical": "utility_bill",
17
    "document_type_detected": "utility_bill",
18
    "document_date": "2026-07-02",
19
    "period_start": "2026-06-01",
20
    "period_end": "2026-06-30",
21
    "age_days": 56,
22
    "max_age_days": 90,
23
    "issuing_country": "GB",
24
    "address_type": "residential",
25
    "cross_reference": {
26
      "overall_score": 0.82,
27
      "name_score": 0.97,
28
      "address_score": 0.72,
29
      "partial": true,
30
      "partial_reasons": ["unit_mismatch"],
31
      "component_scores": {
32
        "first_name": 1.0,
33
        "last_name": 0.95,
34
        "line1": 0.78,
35
        "city": 1.0,
36
        "postcode": 1.0,
37
        "unit": 0.0
38
      }
39
    },
40
    "policy": {
41
      "preset": "uk",
42
      "address_match_pass": 0.8,
43
      "address_match_review": 0.55
44
    }
45
  }
46
}

details.issuer, details.holder_names, and details.extracted_address are personal data. They are returned only on PII-bearing surfaces, are subject to your organization’s sensitive-data access window, and are never exposed through the MCP server.

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.

Related

• Workflows — Orchestrate checks into verification pipelines
• Screening & Reports — AML screening and continuous monitoring
• Fraud Signals — The 150+ signals behind risk assessment