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.

Models

Inquiry

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.

Verification

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.

Document

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.

Template

An inquiry configuration from which to spawn inquiry instances. 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.

Account

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.

Report

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.

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.

created

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

pending

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

completed

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

failed

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

Event created: inquiry.failed

expired

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

Event created: inquiry.expired

needs-review

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

approved

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

Event created: inquiry.approved

declined

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

Event created: inquiry.declined

Verification statuses

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

created

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

submitted

The verification was submitted for processing on an inquiry.

Event created: verification.submitted

passed

The verification passed all required checks run during processing.

Event created: verification.passed

failed

The verification failed at least one required check during processing.

Event created: verification.failed

canceled

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