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 that prevent the inquiry flow from being usable. These generally occur on initial load.
| 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. |
'inactive_template' | 422 | An attempt was made to create an inquiry from an inactive template. Activate the template before attempting to create inquiries. |
'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 verification 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. |
| load-camera-failed | The inquiry flow failed to load the camera during a government ID capture, selfie, or document upload flow. This can happen due to missing permissions or a hardware error. |
| 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. |
Updated over 3 years ago