Document verification

The ID_VERIFICATION module authenticates a government-issued identity document, extracts its fields, and outputs the document portrait so face match can compare it to the selfie. It runs inside the hosted flow: the applicant photographs the document (front, and back when required), and the engine does OCR, machine-readable-zone parsing, and authenticity analysis server-side.

Supported document families

The engine treats these families as first-class types, each with its own classifier label and field template:

What the engine extracts

Fields are read from the MRZ where present and from visual OCR otherwise:

• Full name (and first / last where the document splits them)
• Document number
• Date of birth, date of expiry
• Nationality / issuing country
• The document portrait (for face match)
• On non-Latin documents, a romanised / English read of the same fields (translated_fields)

MRZ parsing (passports and other TD1/TD3 documents) cross-checks the printed data against the MRZ check digits. Barcode / PDF417 data, where a document carries it, is decoded for the same fields.

Authenticity and tamper checks

Beyond reading the document, the engine runs forgery / tamper analysis (EXIF-rule checks plus TruFor tamper localisation on the hosted forensics engine). Two config keys control the outcome:

• forgery_check — enable tamper analysis.
• forgery_action — hold (default) routes a suspected forgery to manual review and gates the applicant at the document step (they see a "couldn't verify this document" screen and, if allow_bypass is on, a Continue-anyway option). flag does not gate the applicant — the document step can still approve so they proceed normally — but silently force-holds the whole session for review (session.metadata.background_review) so an operator sees the finding without tipping off a fraudster mid-flow.

Restricting which documents are accepted

How scoring and decisioning works

ID_VERIFICATION never outputs a single numeric "pass score" the way a credit-risk model might — the terminal status is derived from a set of boolean checks plus a quality_score, evaluated in order:

Common decline / review reasons

Risk-list screening

The extracted document number is screened against the tenant's risk lists (identifier type). A matching list entry can route the session to review, open a case, or block it depending on the list's configured action.

Result shape

ID_VERIFICATION returns the extracted fields, the detected_type and its confidence, an is_document_valid flag, and whether a portrait was found. Retrieve it from GET /v3/session/<id>/ (full result) or in summary form from decision_v3.id_verifications on the decision endpoint.

{
  "feature": "ID_VERIFICATION",
  "status": "approved",
  "score": 91.0,
  "warnings": [],
  "data": {
    "fields": {
      "full_name": "AARAV SHARMA",
      "document_number": "PA1234567",
      "date_of_birth": "1990-04-12",
      "expiry_date": "2032-01-10",
      "nationality": "NP",
      "issuing_state": "NP"
    },
    "translated_fields": {},
    "detected_type": "passport",
    "confidence": 0.97,
    "is_document_valid": true,
    "has_portrait": true
  }
}

Fetch it directly:

curl -s "$TF_BASE_URL/v3/session/$SESSION_ID/" \
  -H "x-api-key: $TF_API_KEY" \
  | jq '.results[] | select(.feature == "ID_VERIFICATION")'

const res = await fetch(`${process.env.TF_BASE_URL}/v3/session/${sessionId}/`, {
  headers: { "x-api-key": process.env.TF_API_KEY! },
});
const session = await res.json();
const idResult = session.results.find((r: any) => r.feature === "ID_VERIFICATION");
console.log(idResult.status, idResult.data.fields);

import requests

session = requests.get(
    f"{BASE_URL}/v3/session/{session_id}/",
    headers={"x-api-key": API_KEY},
    timeout=15,
).json()
id_result = next(r for r in session["results"] if r["feature"] == "ID_VERIFICATION")
print(id_result["status"], id_result["data"]["fields"])

Edge cases

Related