persona-hello-world

Persona Hello World

Overview

Create a Persona inquiry, generate an embed URL for the verification flow, and poll for the inquiry status. Uses the real Persona REST API with sandbox credentials.

Prerequisites

• Completed persona-install-auth setup
• An Inquiry Template ID from the Persona Dashboard (format: itmpl_*)

Instructions

Step 1: Create an Inquiry

import os, requests

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

# Create a new inquiry from a template
resp = requests.post(f"{BASE}/inquiries", headers=HEADERS, json={
    "data": {
        "attributes": {
            "inquiry-template-id": "itmpl_YOUR_TEMPLATE_ID",
            "reference-id": "user-12345",  # Your internal user ID
        }
    }
})
resp.raise_for_status()
inquiry = resp.json()["data"]
inquiry_id = inquiry["id"]
status = inquiry["attributes"]["status"]
print(f"Inquiry created: {inquiry_id} (status: {status})")

Step 2: Get the Verification URL

# The inquiry includes a session token for the embedded flow
session_token = inquiry["attributes"].get("session-token")
if session_token:
    # Option A: Hosted flow (redirect user to Persona)
    hosted_url = f"https://withpersona.com/verify?inquiry-id={inquiry_id}&session-token={session_token}"
    print(f"Send user to: {hosted_url}")

    # Option B: Embedded flow (JavaScript SDK in your page)
    print(f"Embed with: Persona.Client({{ templateId: 'itmpl_...', inquiryId: '{inquiry_id}' }})")

Step 3: Poll for Completion

import time

for _ in range(30):  # Poll for up to 5 minutes
    resp = requests.get(f"{BASE}/inquiries/{inquiry_id}", headers=HEADERS)
    resp.raise_for_status()
    status = resp.json()["data"]["attributes"]["status"]
    print(f"  Status: {status}")

    if status in ("completed", "approved", "declined"):
        break
    time.sleep(10)

# Get verification details
if status == "completed":
    verifications = resp.json()["data"]["relationships"]["verifications"]["data"]
    for v in verifications:
        print(f"  Verification: {v['type']} — {v['id']}")

Step 4: Retrieve Verification Results

# Get detailed verification result
verification_id = verifications[0]["id"]
v_resp = requests.get(f"{BASE}/verifications/{verification_id}", headers=HEADERS)
v_resp.raise_for_status()
v_data = v_resp.json()["data"]["attributes"]
print(f"  Check: {v_data['status']}")
print(f"  Name: {v_data.get('name-first', 'N/A')} {v_data.get('name-last', 'N/A')}")

Output

• Inquiry created with unique ID
• Hosted or embedded verification URL generated
• Inquiry status polled until completion
• Verification results retrieved

Error Handling

Error	Cause	Solution
422 Unprocessable	Invalid template ID	Verify template ID in Dashboard
Inquiry stays created	User hasn't started flow	Share the hosted URL with user
Empty verifications	Inquiry not completed	Wait for user to complete verification
404 Not Found	Wrong inquiry ID	Check ID format: inq_*

Resources

• Inquiries Overview
• Accessing Inquiry Status
• API Quickstart Tutorial

Next Steps

• Build full KYC flow: persona-core-workflow-a
• Handle webhook events: persona-webhooks-events