Persona
Persona is an identity verification and KYC/KYB compliance platform. These tools provide read access to verification data, case management, and system audit information.
Entity Hierarchy
- Accounts — end-user identity records. Each account may have multiple inquiries over time.
- Inquiries — individual verification attempts (document check, selfie, database lookup). Each inquiry progresses through statuses: created → pending → completed/failed/expired.
- Inquiry Sessions — browser/mobile sessions within an inquiry. One inquiry can span multiple sessions (e.g., user closes and reopens the verification flow).
- Cases — escalated reviews. Created automatically by workflow rules or manually by compliance staff. A case references one or more inquiries.
- Workflows Run — execution records of automated decision logic (auto-approve, flag, escalate).
- Events — system-wide event log (inquiry.completed, case.updated, account.created, etc.).
- Webhooks — registered HTTP endpoints receiving real-time event notifications.
- API Logs — raw request/response audit trail for every API call.
Workflows
Verification audit: List inquiries to see all verification attempts. Filter by status to find failed or expired ones. Cross-reference with inquiry sessions to see if users abandoned mid-flow.
Case review: List cases to find escalated verifications. Each case links back to the triggering inquiry and account. Use events to see the timeline of actions taken on a case.
Compliance monitoring: List workflow runs to see which automated rules fired. Combine with events to build a full audit trail of decisions. Use API logs to confirm webhook deliveries.
System health: List webhooks to confirm notification endpoints are registered. Check API logs for error patterns or unusual activity.
Gotchas
- All tools are read-only list endpoints — no create, update, or delete operations. Use the Persona dashboard or API directly for mutations.
- Pagination: All list endpoints return paginated results. Pass cursor values from previous responses to page through large datasets.
- Account vs Inquiry: An account is a person; an inquiry is a single verification attempt. One person may have many inquiries across different verification templates.
- Inquiry Sessions vs Inquiries: Sessions track the user's browser interaction. Multiple sessions per inquiry is normal (user closes tab, returns later).
- Event ordering: Events are returned newest-first. For chronological audit trails, reverse the results.
