Retrieving and Understanding Onboarding Status

Status Codes

Session status codes, also commonly called onboarding statuses, are flags that tell you when certain operations of the flow are complete and the data is ready to be fetched. For example, once you receive the ONBOARDING_FINISHED status, you can safely fetch any data that was collected during the user's onboarding session. Similarly, once you receive the FACE_VALIDATION_FINISHED or any status suffixed with FINISHED, you can safely fetch the data associated with those modules. The possible onboarding statuses include:

• ID_VALIDATION_FINISHED: User completed capturing the ID document

• POST_PROCESSING_FINISHED: ID postprocessing completed on the server

• FACE_VALIDATION_FINISHED: User completed the selfie capture

• GOVERNMENT_VALIDATION_FINISHED: User completed government validation

• ONBOARDING_FINISHED: User completed the onboarding process

• MANUAL_REVIEW_APPROVED: A session that was in a Needs Review state, was manually approved by an executive

• MANUAL_REVIEW_REJECTED: A session that was in Needs Review state, was manually rejected by an executive

• UNKNOWN: Unable to determine the status of the onboarding session

• This occurs when a user hasn't started the onboarding or the user is still in the process of capturing their ID

Webhooks

Webhooks are the recommended way to receive automatic updates for onboarding status changes as well as status changes for other services. As a user progresses through their ID verification journey, a webhook notification is sent to the server URL specified in the configuration tab of the Dashboard.

These webhooks are currently supported:

• Onboarding status webhook - Triggered every time the status changes for an Onboarding Session.

• Videoselfie upload webhook - Triggered when the video selfie recording file (if applicable) becomes available.

• Global watchlists webhook - Triggered when a global watchlist result is updated.

• Face Authentication webhook - Triggered when a face authentication either succeeds or fails.

• Work history webhook - Triggered after processing the work history search for a user. This webhook is exclusive to Mexico.

• Proof of payment webhook - Triggered after processing the payment proof validation for a user. This webhook is exclusive to Mexico.

• Session webhooks - Set of four webhooks triggered by specific events during any type of session from a Flow or Workflow:

• Session Started

  • Session Failed
  • Session Succeeded
  • Session Pending Review

The following webhooks either have been or are soon to be deprecated:

• Authentication webhooks - (soon to be deprecated) Available for 1:1 and 1:N. These contain information about the login attempt, any Identities which could match the face reported by the login, and the Onboarding Session (or interview) which best matches the biometric of the face used to login.
• INE scraping webhook - (Deprecated) Provided INE Scraping results asynchronously.

To learn more about:

• Available webhooks and a technical overview, review the Webhooks articles starting here.
• Configuring webhooks in the Dashboard, read this Dashboard User Docs article.

Polling

An alternative to webhooks is to use polling. Polling is only available for fetching an onboarding status. For the other services listed under the webhooks section, you will need to utilize our webhooks. Polling isn't recommended since it requires continuous API calls to check the status of an onboarding session, however if it is necessary for your integration, you can poll for the onboarding status using this endpoint. If you only want to know when the data is done processing, call this endpoint.