Decisions

Both API surfaces expose a stable decision that is deliberately coarser than the raw workflow status. Branch your integration on the decision, not on the status. Raw statuses exist for diagnostics and can change or gain new values; the decision set is the contract.

Session decisions (/v3)

For a ThirdFactor Verify session, decision collapses the raw status to one of five values:

Read it with the compact decision endpoint:

curl -H "x-api-key: $TF_API_KEY" "$BASE/v3/session/6f0e2b7a-…/decision/"

const res = await fetch(`${BASE}/v3/session/${sessionId}/decision/`, {
  headers: { "x-api-key": process.env.TF_API_KEY },
});
const { decision, decision_v3, reason } = await res.json();
if (decision === "approved") {
  // safe to grant access / open the account here
}

resp = requests.get(
    f"{BASE}/v3/session/{session_id}/decision/",
    headers={"x-api-key": os.environ["TF_API_KEY"]},
)
body = resp.json()
if body["decision"] == "approved":
    ...  # safe to grant access / open the account here

{
  "session_id": "6f0e2b7a-…",
  "status": "approved",
  "decision": "approved",
  "decision_v3": {
    "id_verifications": [],
    "liveness_checks": [],
    "face_matches": [],
    "aml_screenings": [],
    "reviews": []
  },
  "reason": ""
}

decision_v3 — the per-module breakdown

decision_v3 groups every module result the workflow produced into typed arrays, so you can see why a session landed where it did without parsing raw module output. Each entry in an array carries the module's own node_id (matters once a feature repeats — see Workflows), its status, a score where applicable, any warnings, and a module-specific data object:

{
  "decision_v3": {
    "id_verifications": [
      {
        "node_id": "ID_VERIFICATION",
        "status": "approved",
        "score": 0.97,
        "warnings": [],
        "data": { "document_type": "passport", "country": "NPL" }
      }
    ],
    "liveness_checks": [
      { "node_id": "LIVENESS", "status": "approved", "score": 0.99, "warnings": [], "data": { "method": "PASSIVE" } }
    ],
    "face_matches": [
      { "node_id": "FACE_MATCH", "status": "approved", "score": 0.93, "warnings": [], "data": {} }
    ],
    "aml_screenings": [
      { "node_id": "AML_SCREENING", "status": "approved", "score": 0.0, "warnings": [], "data": { "hits": 0 } }
    ],
    "reviews": []
  }
}

Additional keys such as nfc_verifications, poa_verifications, phone_verifications, email_verifications, ip_analyses, database_validations and questionnaire_responses appear when those modules run. Empty arrays mean the category was not part of this workflow — not that the module failed.

Application decisions (/api/v1)

For an application, workflow statuses are more granular than the public contract. Prefer application.decision.

Raw statuses such as form_filled, sdk_redirected, completed and kyc_failed may still appear for workflow diagnostics. Do not build long-term external branching on raw statuses unless it is agreed in your integration contract.

Comparing the two decision contracts

Why a session lands in review

A session becomes manual_review / in_review rather than a clean pass or fail when:

• A module scored inside its review band rather than clearly passing or failing (e.g. a face match just under threshold).
• AML screening returned a hit, or could not run — screening fails closed.
• A module with no real web implementation (currently NFC verification and database validation) is enabled by a legacy or imported workflow. Rather than fake a pass, the engine routes it to review so a human decides.
• The applicant used "Continue anyway" after a failed check, where the module allows bypass.
• An operator manually held it.

An operator resolves it in Console → Verifications. Approving or declining there emits the terminal webhook and, for flow-spawned sessions, resumes the parent application.

Edge cases

• A session with zero populated arrays. A session that reached a terminal state without running any module (e.g. abandoned at the welcome screen) has every decision_v3 array empty. That's a legitimate response, not a bug — check decision and status first, then use decision_v3 to explain why.
• AML "could not run." Because AML screening fails closed, a transient upstream outage on the screening provider routes the session to manual_review rather than silently skipping the check or passing it — don't treat a missing aml_screenings result as a pass.
• Reason string is empty on a clean approval. reason is populated for reviews and declines; on a straightforward approved decision it is typically "". Don't treat an empty reason as an error.
• Retrying a read after an operator overrides the status. update-status/ changes the authoritative decision immediately; a decision read issued right after should reflect the override, but always re-read rather than caching a decision you fetched before the override.

The golden rule

FAQ

Related