persona-core-workflow-b

Persona Core Workflow B — Verification Checks

Overview

Work with Persona's verification types: government ID (passport, driver's license), selfie liveness detection, and database checks (SSN, watchlist). Covers retrieving verification details, interpreting check results, and handling edge cases.

Prerequisites

• Completed persona-core-workflow-a (inquiry flow)
• Inquiry Template with verification checks configured

Instructions

Step 1: List Verifications for an Inquiry

import os, requests

HEADERS = {
    "Authorization": f"Bearer {os.environ['PERSONA_API_KEY']}",
    "Persona-Version": "2023-01-05",
}
BASE = "https://withpersona.com/api/v1"

# Get all verifications for an inquiry
resp = requests.get(f"{BASE}/inquiries/inq_XXXXX", headers=HEADERS)
resp.raise_for_status()
inquiry = resp.json()["data"]
verifications = inquiry["relationships"]["verifications"]["data"]

for v in verifications:
    v_resp = requests.get(f"{BASE}/verifications/{v['id']}", headers=HEADERS)
    v_data = v_resp.json()["data"]["attributes"]
    print(f"  Type: {v['type']}")
    print(f"  Status: {v_data['status']}")  # passed, failed, requires_retry
    print(f"  Checks: {v_data.get('checks', [])}")

Step 2: Government ID Verification Results

# Government ID verification includes extracted data
def get_gov_id_details(verification_id: str) -> dict:
    resp = requests.get(f"{BASE}/verifications/{verification_id}", headers=HEADERS)
    resp.raise_for_status()
    attrs = resp.json()["data"]["attributes"]

    return {
        "status": attrs["status"],
        "first_name": attrs.get("name-first"),
        "last_name": attrs.get("name-last"),
        "dob": attrs.get("birthdate"),
        "id_number": attrs.get("identification-number"),
        "id_class": attrs.get("id-class"),          # dl, pp, id
        "country": attrs.get("country-code"),
        "expiry": attrs.get("expiration-date"),
        "checks": {
            check["name"]: check["status"]
            for check in attrs.get("checks", [])
        },
    }

# Example checks: id_barcode_detection, id_integrity, id_selfie_comparison

Step 3: Selfie Liveness Check

def get_selfie_result(verification_id: str) -> dict:
    resp = requests.get(f"{BASE}/verifications/{verification_id}", headers=HEADERS)
    attrs = resp.json()["data"]["attributes"]

    return {
        "status": attrs["status"],
        "center_photo_url": attrs.get("center-photo-url"),
        "checks": {
            check["name"]: check["status"]
            for check in attrs.get("checks", [])
        },
        # Key checks: selfie_pose_detection, selfie_liveness_detection
    }

Step 4: Database Verification (SSN, Watchlist)

def get_database_check(verification_id: str) -> dict:
    resp = requests.get(f"{BASE}/verifications/{verification_id}", headers=HEADERS)
    attrs = resp.json()["data"]["attributes"]

    return {
        "status": attrs["status"],
        "checks": {
            check["name"]: {
                "status": check["status"],
                "reasons": check.get("reasons", []),
            }
            for check in attrs.get("checks", [])
        },
        # Key checks: database_ssn_check, database_watchlist_check
    }

Step 5: Decision Logic

def make_verification_decision(inquiry_id: str) -> str:
    resp = requests.get(f"{BASE}/inquiries/{inquiry_id}", headers=HEADERS)
    verifications = resp.json()["data"]["relationships"]["verifications"]["data"]

    all_passed = True
    for v in verifications:
        v_resp = requests.get(f"{BASE}/verifications/{v['id']}", headers=HEADERS)
        status = v_resp.json()["data"]["attributes"]["status"]
        if status != "passed":
            all_passed = False
            print(f"  FAILED: {v['type']} — {status}")

    return "approved" if all_passed else "manual_review"

Output

• Verification results retrieved with extracted data
• Government ID fields (name, DOB, ID number) parsed
• Selfie liveness status checked
• Database checks (SSN, watchlist) interpreted

Error Handling

Verification Status	Meaning	Action
passed	All checks passed	Approve user
failed	One or more checks failed	Decline or manual review
requires_retry	Poor image quality	Ask user to retry
initiated	Check still running	Poll again

Resources

• Government ID Verifications
• Verification Checks

Next Steps

• Handle events via webhooks: persona-webhooks-events
• Debug verification issues: persona-common-errors