API Reference

Advance - Liveness Detection and Face Matching

Liveness detection and face matching provide a secure biometric verification process to ensure real-time user authenticity. The system involves multiple steps to prevent spoofing and ensure that the user is both physically present and matches the registered identity.

The Process

The complete liveness detection and face matching workflow includes three main steps:

  1. Start Liveness Session
  2. Integrate Liveness in Frontend
  3. Match Liveness Face

These steps work together to authenticate users using live face recognition and verify their identity securely.

1️⃣ Start Liveness Detection Session

  • The client sends a POST request to the /start-liveness-session/ endpoint.
  • The backend generates a unique sessionId to identify and manage the liveness detection session.
  • This sessionId is returned in the response and must be passed to the frontend for further processing.

2️⃣ Frontend Liveness Integration

  • The frontend uses the sessionId received from Step 1 to initiate the liveness session on the client side.
  • Users interact with the live detection component (camera) to capture a real-time face.
  • This component ensures that the user is not using spoofing methods (e.g., photo or video playback).
  • For implementation details and how the frontend works, refer to the Frontend Integration Guide click here.

3️⃣ Check Liveness and face matching

Once the frontend completes capturing a live photo, it should immediately call the check-liveness API (/check-liveness/). This API performs two critical actions:

  • ✅ Liveness Detection – Validates whether the user is genuinely present in front of the camera (i.e., not a spoof or static image).
  • 🧠 Face Matching – Automatically compares the captured face with the previously enrolled face image that was stored during user registration.

This ensures both identity verification and real-time user presence in a seamless and secure process.