Simulate Face Match

Bypass verification when testing

Simulation Mode

When developing and testing your Face Match integration, you can use simulation mode to test different scenarios without performing actual liveness checks. This makes development and testing much faster and more efficient.

Simulation mode is only available in the sandbox environment

How to Use Simulation Mode

To use simulation mode, simply add the simulate query parameter when getting a Face Match session_id.

When you navigate to the user with that session, the page will wait for 3 seconds before redirecting with the simulated response, mimicking the real-world flow.

The session will redirect with the same error or success case that you specified in the simulate parameter.

Available Simulation Cases

The following simulation cases are available for testing:

• invalid_session_id - Simulates an invalid session ID error
• session_id_not_found - Simulates a case where the session ID cannot be found
• failed_to_get_camera_permission - Simulates a camera permission failure
• failed_to_complete_face_scan - Simulates a face scan failure
• failed_to_collect_device_data - Simulates a device data collection failure
• liveness_check_failed - Simulates a failed liveness check
• success - Simulates a successful verification

Example Testing Flow

1. Add the simulate parameter to GET /liveness/session with the case you want to test

GET /liveness/session?simulate=liveness_check_failed

{
    "request_id": "c6716efe-3624-4813-9a59-175d8fee484c",
    "session_id": "{some-simulated-session-id}"
}

2. Navigate to the Face Match URL like normal and wait 3 seconds

https://app.sandbox.verisoul.ai?session_id={some-simulated-session-id}

3. The page will redirect you with the correct error or success message, bypassing any liveness or document checks

https://verisoul.ai?session_id={some-simulated-session-id}&success=false&error_message=liveness_check_failed

Choose the Decision and Score

With simulate=success, you can set the outcome that comes back by adding these optional parameters to GET /liveness/session:

Parameter	Values	Description
simulate_decision	Real, Suspicious, Fake	The decision returned by /verify-face and the webhook.
simulate_risk_score	0 to 1	The risk_score returned by /verify-face and the webhook.
simulate_risk_flags	Comma-separated flag names, up to 20	The risk_flags returned by /verify-face and the webhook. Use lowercase names such as vpn_detected,repeat_face.

When you pass only simulate_decision, risk_score is filled with a typical value: 0.1 for Real, 0.5 for Suspicious and 0.9 for Fake. Values are returned as you send them. Verisoul does not compare the decision to the score or to your project thresholds.

If you pass simulate_decision or simulate_risk_score without simulate_risk_flags, risk_flags is an empty list. If you pass none of the three, you receive the default stubbed response (decision Fake).

These parameters require simulate=success. A request that sends them with any other simulate value, or an invalid value, returns a 400 with invalid_simulated_session.

Examples

# Approval path
GET /liveness/session?simulate=success&simulate_decision=Real

# Manual review path with a specific score
GET /liveness/session?simulate=success&simulate_decision=Suspicious&simulate_risk_score=0.55

# Rejection path with specific flags
GET /liveness/session?simulate=success&simulate_decision=Fake&simulate_risk_score=0.95&simulate_risk_flags=repeat_face,vpn_detected

Session Data in Responses

Responses for simulated sessions carry the data of the session you created. The metadata object in /verify-face and in the webhook contains the real project_id, session_id, request_id and timestamp. account_id is the account_id you passed when creating the session, or null. referring_session_id is the referring_session_id you passed, or null. You can match a simulated webhook to your own records the same way you match a real one.

Webhooks

Simulated sessions send the same webhooks as real sessions, to the endpoints subscribed in your project:

simulate value	Webhook
success	verification.face-match.completed with status: "success". The data object matches the /verify-face response for the session.
liveness_check_failed, face_match_failed, failed_to_collect_device_data	verification.face-match.completed with status: "error" and the matching error code.
invalid_session_id, session_id_not_found	No webhook. These cases only redirect the user.

The webhook is sent when the simulated session finishes, about 3 seconds after the user opens the session URL.

API Responses

When calling the API with sessions that have been simulated you can expect:

• For success case: You receive a stubbed response that uses the decision, score and flags you set, or the default stub values when you set none. metadata comes from the real session.
• For all other cases: You receive a 400 response

The error responses in simulation mode may not exactly match the production error responses. They are intended for testing the basic flow of your integration.

This allows you to test your integration’s error handling and success flows without needing to perform actual verifications.