Database validation

The DATABASE_VALIDATION module is designed to cross-check an applicant's extracted identity data (name, document number, date of birth) against an external authoritative database — for example a government identity registry or a credit-bureau identity file. It confirms that the person the document describes actually exists in a system of record, complementing the document-authenticity checks that verify the document itself.

Current behaviour

Because it has no real check to perform, the module is hidden from the workflow builder. It can still appear in a legacy or imported workflow, which is exactly why the engine fails safe: rather than wedging the session or faking a pass, it hands the decision to a human operator so nothing silently slips through.

This is the same fail-safe treatment applied to NFC_VERIFICATION on a non-native host — both are members of the engine's UNIMPLEMENTED_MODULES set. At session-completion time the engine sweeps any still-pending result for these features and finalises it to review with a clear reason code instead of a silent approval.

Fail-closed vs fail-open

What you get

When the module runs it produces an in_review result:

{
  "feature": "DATABASE_VALIDATION",
  "status": "in_review",
  "score": null,
  "warnings": ["database_validation_not_available"],
  "data": {
    "reason": "database_validation_not_available",
    "engine": "unavailable"
  }
}

Alongside it, a timeline entry is logged (module.unavailable, "DATABASE_VALIDATION has no automated check — held for review"). The session's overall status therefore lands at review whenever this module is present and unresolved. An operator adjudicates it in Console → Verifications.

Read the result the same way as any module:

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

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 dbv = session.results.find((r: any) => r.feature === "DATABASE_VALIDATION");
console.log(dbv?.status, dbv?.warnings); // "in_review" ["database_validation_not_available"]

import requests

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

When you'd enable it

Turn this module on only once an external provider is integrated for your deployment — a government identity registry, a national ID verification API, or a bureau identity file appropriate to your market. Until that wiring exists, enabling the step only adds a guaranteed review to every session, so it's off (and hidden) by default.

FAQ

Related