Biometric Authentication Integration

Use this guide when your workflow runs Biometric Authentication, to compare a client's live selfie against a previously verified identity.

Biometric Authentication is typically used for returning clients. A newly captured selfie is compared against an identity established during an earlier identity verification workflow.

This guide extends API v2 integration.

Before you begin

Make sure you have:

• API credentials for sandbox and production.
• A Biometric Authentication workflow configured (for example BiometricsOnly).
• Handling for workflow statuses and Identity Verification product statuses.
• Optional: Webhooks.

Biometric Authentication results are reported under the IdentityVerification product. A workflow status of completed indicates that processing has finished, not that the biometric comparison succeeded. To determine the outcome, inspect the product status.

Returning clients

Biometric Authentication usually requires an existing Fourthline identity.

When the client previously completed Identity Verification, pass the existing clientId during workflow creation.

Use partnerClientId only when your configuration supports creating or linking a client during the Biometric Authentication workflow.

Minimum viable integration

API-only flow

1. Create workflow
2. Upload required files
3. Start workflow
4. Monitor workflow status
5. Retrieve reports

SDK flow

1. Create workflow
2. Create SDK session
3. Complete capture in the SDK
4. Start workflow
5. Monitor workflow status
6. Retrieve reports

Optional: replace polling with webhooks. After each webhook event, call Get workflow status to retrieve the latest workflow state.

1. Create workflow

Call Create workflow.

Returning client

{
  "workflow": "BiometricsOnly",
  "clientId": "fourthline-client-uuid"
}

New or linked client

{
  "workflow": "BiometricsOnly",
  "partnerClientId": "your-partner-client-id"
}

Requirements

• Set workflow to your workflow name
• Provide either clientId or partnerClientId
• Do not provide both
• Store workflowId and clientId from the response

API reference: Create workflow

2. Choose how capture is provided

See:

• App Drop-in setup
• Web SDK setup
• Web UI customization

3. Required uploads (API-only)

Skip this section when capture is performed through the Mobile SDK or Web SDK.

Required uploads depend on your configuration.

The most common Biometric Authentication configuration requires:

Some configurations may require additional metadata or reference information.

Upload files using Upload client document.

Do not call Start workflow until all required files and metadata have been uploaded.

4. SDK integration

After creating the workflow:

1. Call Create SDK session
2. Provide:
   • workflowId
   • target (Mobile or Web)
3. Pass the returned validationCode from your backend to the SDK
4. Let the client complete capture
5. Start the workflow
6. Monitor workflow status

API reference: Create SDK session

5. Monitor status

Use the same two-layer status model as Workflows integration.

Webhooks

Webhook events contain details.status but do not contain workflowStatus.

After receiving a webhook:

1. Call Get workflow status
2. Retrieve the latest workflow state
3. Check the Identity Verification product status

6. Retrieve reports

After the workflow reaches completed:

Get workflow status returns products\[].status while the JSON report returns products\[].productStatus. Use the appropriate field for the endpoint you are calling. See Workflow reports.

API-only integration

After creating the workflow and uploading required files:

1. Call Start workflow
2. Expect HTTP 202 with an empty response body
3. Poll Get workflow status
4. Retrieve reports when processing completes
   
   

For authentication, workflow creation, and reporting concepts, see API v2 integration.

Handle common errors

For additional scenarios, see API v2 integration — Handle common errors.

Support

For questions about your workflow configuration or signing setup, contact your Fourthline delivery manager.