DocumentationAPI Reference
DocumentationAPI Reference

Client Callbacks

onComplete

The onComplete callback is called when the inquiry has completed the inquiry flow and the individual clicks on the complete button to close the flow.

Parameter

Type

Description

{ inquiryId, status, fields }

Object

Object containing information about the completed inquiry.

inquiryId is the ID of of the inquiry used in this instance of the flow.

status is the status of the completed inquiry (e.g. 'completed', 'failed').

fields is a map of field values. See Fields documentation.

onLoad & onReady

The onLoad callback is called when the iframe finishes loading and is ready to be displayed. It does not take any arguments.

The onReady callback is called when the inquiry flow is ready for user interaction. It does not take any arguments.

onCancel

The onCancel callback is called when an individual cancels the inquiry flow before completion.

Parameter

Type

Description

{ inquiryId, sessionToken }

Object

Object containing information about the canceled inquiry.

inquiryId is the ID of of the inquiry used in this instance of the flow.

sessionToken is a token that can be used to resume the inquiry.

Values will be undefined if the flow is canceled before an inquiry is created.

onError

The onError callback is called in response to errors in the inquiry flow.

Parameter

Type

Description

{ status, code }

Object

Error object.

status is the HTTP error status, if applicable. The code will be 0 if the error was an application error.

code is a short string describing the error.

Below is a list of Persona error codes.

Error codes

Status

Meaning

'application_error'

0

An internal error occurred in the Persona web application. Please contact support.

'invalid_config'

400

The persona client was initialized with invalid arguments.

'unauthenticated'

409

An inquiry was resumed without a valid sessionToken. Retrieve one from the external API and pass it to the client.

'unknown'

number

Catch-all error.

onEvent

The onEvent callback is called at certain points in the Persona flow. It takes two arguments, an eventName string and a metadata object.

🚧

Do not use this for critical flows

onEvent exists for analytics purposes but the events passed through are potentially lossy. If your business logic depends on granular verification and inquiry status changes, we recommend using Webhooks.

Parameter

Type

Description

eventName

String

A string representing the event that has just occurred in the Persona flow.

metadata

Object

An object containing information about the event.

Example metadata for a verificationverification - A validation of the personal information submitted by an individual. status change event:

{
  "id": "ver_rMkwDnyoZy6b1jDSofjUtL5z",
  "status": "<submitted|passed|failed>"
}

Other supported events include:

start

The individual has begun progressing through the flow after clicking 'Continue' on the start screen.

Dynamic Flow Templates will send this event at the same time as 'ready', and it will not indicate user interaction.

country-select

Deprecated. The individual confirmed the country of their ID.

Dynamic Flow Templates will not send this event.

verification-change

Deprecated. The status of an in-progress verification changed.

Dynamic Flow templates will not send this event.

document-camera-select

The individual is opening the camera for the government ID verification.

document-camera-capture

The individual took a photo for the government ID verification.

document-upload

The individual uploaded a government ID photo.

selfie-camera-select

The individual is opening the camera for the selfie verification.

selfie-camera-capture

The individual took a photo for the selfie verification.

selfie-record-upload

The individual uploaded a selfie photo. We allow uploads when their browser does not support embedded video.

one-time-link-sent

The individual sent a one time link to their mobile device.

one-time-link-start

The individual resumed their flow on their mobile device using a one-time link.

one-time-link-exit

The individual returned to their initial device after sending a link to their mobile device.

complete

The individual is exiting the flow after verifying their identity.