DocumentationAPI Reference
DocumentationAPI Reference

Models & Lifecycle

Before integrating Persona, let's understand how all of the key integration concepts fit together and get a holistic overview of how an individual verifies their identity.


A single instance of an individual's attempt to verify their identity. The inquiry itself can contain verifications that can be configured through a template.

Inquiry Template

An inquiry configuration from which to spawn inquiry instances. Inquiry Templates define what information should be collected, what verifications should be run, and how they should be run. To learn more about the different verification types, refer to Verification Types.

Inquiry Template Version

The specific configuration of an Inquiry Template. You can integrate with Inquiry Template IDs or Inquiry Template Versions, the difference being the Inquiry Template IDs can dynamically update while versions are immutable once published.

Inquiry lifecycle

Inquiries move through a series of statuses from creation to completion. These statuses allow you to track where individuals are in the process, and trigger webhooks to take actions if needed.

Inquiry statuses

Inquiries change statuses when:

  1. The individual interacts with the inquiry
  2. You (the organization) interact with the inquiry
  3. The inquiry is updated due to some scheduled or asynchronous work

Events are created when inquiries change statuses. These events can be listened to using Webhooks.


Initial status when an inquiry is created from the dashboard, via API, or automatically through a Hosted Flow or Embedded Flow link.

Event created: inquiry.created


Status when an individual starts to submit information (verifiable information or documents) to an inquiry for verification but before an inquiry reaches a terminal state.

Event created: inquiry.started


Status when all information has been collected and all verifications have passed. No additional interaction is required from the individual.

Additional asynchronous work:

  • Reports will run at this time if your organization has reports configured to run when an inquiry completes.

Event created: inquiry.completed


Status when the number of allowed verification attempts has been exceeded and the individual can no longer continue.

Event created: inquiry.failed


Status when an inquiry expires. Inquiries expire after 24 hours to ensure inquiry freshness.

Event created: inquiry.expired


Status when an inquiry has been marked for review. This can be done manually through the dashboard, through API, or through a Workflow.

Event created: inquiry.marked-for-review


Status when an inquiry has been approved through the dashboard, API, or a workflow.

Event created: inquiry.approved


Status when an inquiry has been declined through the dashboard, API, or a workflow.

Event created: inquiry.declined


A process that checks information entered by an individual, using a variety of methods to determine whether or not an individual is identity verified. An inquiry can be configured to have at minimum one verification.

Verification statuses

Verifications change statuses as they are created, submitted, and processed.


The verification for an inquiry was created in the Persona backend. This usually indicates there is an intent to verify information, but is not a guarantee that it is ready to run.

Event created: verification.created


The verification was submitted for processing on an inquiry.

Event created: verification.submitted


The verification passed all required checks run during processing.

Event created: verification.passed


The verification failed at least one required check during processing.

Event created: verification.failed


The verification was canceled. This can happen if a previously created verification (eg. through API or an individual going through an inquiry) times out.

Event created: verification.canceled


A written, printed, or electronic matter provided by an individual, such as a government ID or a utility bill. An inquiry can be configured to collect zero or more documents.


An entity within Persona's system that can map back to accounts within your internal system. Accounts can have multiple inquiries and provide tools to help you stay organized.


Asynchronous fetches for additional information about an individual. Examples include watchlist reports or background checks. Reports can be run after an inquiry completes or continuously on an account.