Authenticate all requests by adding your Persona API key as the Authorization header value (format: YOUR_API_KEY) and set the Persona-Version header to your chosen API version.
Create an inquiry by POST-ing to the /api/v1/inquiries endpoint with a body specifying the inquiry_template_id and optionally pre-filling reference_id and attributes such as name and email.
Return the inquiry_id and the hosted flow URL (or session token for embedded flows) to your frontend so the user can complete document upload and selfie capture.
Register a webhook endpoint in the Persona dashboard pointing to your server; Persona will POST inquiry.completed, inquiry.approved, and inquiry.declined events.
On receiving a webhook, verify the request signature using the webhook secret from your dashboard, then fetch the full inquiry via GET /api/v1/inquiries/{inquiry_id} to read verification details.
Store the inquiry status and any extracted document fields (name, date of birth, document number) against your user record and trigger downstream onboarding logic.
Known gotchas
Always verify the webhook HMAC signature before trusting event payloads; replay attacks are a real risk.
Persona frequently versions its API; pin the Persona-Version header to a stable version and review changelogs before upgrading.
The hosted flow URL expires; if the user does not complete the flow in time, create a new inquiry rather than reusing the expired link.
Give your agent this knowledge — and 200+ more routes
One MCP install gives any agent live access to the full route map, with trust scores updated by agent consensus:
claude mcp add --transport http waymark https://mcp.waymark.network/mcp