Identity Verification (IDV)

Identity Verification (IDV) is a mandatory sub-process of the Onboarding workflow that uses Fourthline to perform remote identification of the user.

Triggering the Flow

The IDV flow is triggered automatically as part of the onboarding Entitlement. Your application will receive a requirementsIDV webhook when the process is ready for the user to perform identification.

Automatic Workflow Creation

When the IDV entitlement starts, a new Fourthline workflow is created automatically by the system. The unique workflow_id for this session is included directly in the webhook payload.

Client Integration

When the requirementsIDV webhook is received, your application should:

1. Extract Workflow ID: The requirementsIDV webhook's details object contains the workflow_id needed for the session.
2. Create a Session: Call POST /persons/{person_id}/fourthline_workflows/{workflow_id}/fourthline_sessions using the workflow_id from the webhook to generate a session for the user.
3. Facilitate Verification: Use the Fourthline SDK (on mobile) or Web SDK to allow the user to perform the identification (ID scan and selfie).

Error Handling & Retries

The IDV process includes a retry mechanism for non-terminal failures (e.g., poor image quality, blurry ID, or inconsistent data).

1. Notification: If Fourthline identifies a fixable issue, the system sends an errorIDV webhook.
2. Details: The webhook payload contains specific error messages indicating what went wrong (e.g., "ID document not readable").
3. Reset: The internal workflow resets the process for that user.
4. New Session: Your application must respond to the errorIDV (or subsequent requirementsIDV) by starting the flow again:
   • Extract the new workflow_id from the webhook.
   • Create a fresh Fourthline session.
   • Prompt the user to re-attempt the identification.

Terminal failures (e.g., fraud detection or definitive rejection) will result in a failedIDV webhook and the termination of the onboarding entitlement.

Webhook Notifications

Webhook	Description
requirementsIDV	Triggered when IDV is required. Contains the workflow_id.
completedIDV	The IDV process was completed successfully.
failedIDV	Terminal failure (unacceptable risk or definitive rejection).
errorIDV	Non-terminal error. A retry is required.

Sequence Diagram