Didit Docs

Biometric Authentication Report

Our Biometric Authentication process provides comprehensive insights into the verification of returning users, helping you understand both the liveness detection and facial matching results in a single verification flow.

Report Structure

The biometric authentication report includes both liveness detection and face matching components, providing a complete picture of the user's authentication attempt.

Core Response Fields

interface BiometricAuthenticationResponse {
  session_id: string;
  session_number: number;
  vendor_data: string;
  status: 'Approved' | 'Declined' | 'Not Finished';
  workflow_id: string;
  liveness: {
    status: 'Approved' | 'Declined' | 'Not Finished';
    method: 'ACTIVE_3D' | 'FLASHING';
    score: number;
    reference_image: string;      // Temporary URL
    video_url: string;           // Temporary URL
    warnings: {
      risk: string;
      additional_data: string | null;
      log_type: 'information' | 'warning' | 'error';
      short_description: string;
      long_description: string;
    }[];
  };
  face_match: {
    status: 'Approved' | 'Declined' | 'Not Finished';
    score: number;
    source_image_session_id: string;
    source_image: string;        // Temporary URL
    target_image: string;        // Temporary URL
    warnings: {
      risk: string;
      additional_data: string | null;
      log_type: 'information' | 'warning' | 'error';
      short_description: string;
      long_description: string;
    }[];
  };
}

Response Fields

Session Information

session_id: Unique identifier for the authentication session
session_number: Sequential number assigned to the session
vendor_data: Customer-provided identifier to link sessions
status: Overall status of the authentication attempt
workflow_id: The type of workflow (always "biometric_authentication")

Liveness Component

liveness.status: Status of the liveness detection
liveness.method: The liveness detection method used
liveness.score: Confidence score for liveness (0-100)
liveness.reference_image: URL to the captured facial image
liveness.video_url: URL to the liveness check video (when applicable)
liveness.warnings: Array of liveness-related warnings and errors

Face Match Component

face_match.status: Status of the face matching comparison
face_match.score: Similarity score between current and reference images (0-100)
face_match.source_image_session_id: The session ID that provided the reference image
face_match.source_image: URL to the reference image from previous verification
face_match.target_image: URL to the current verification image
face_match.warnings: Array of face match-related warnings and errors

Sample Response

{
  "session_id": "11111111-2222-3333-4444-555555555555",
  "session_number": 1234,
  "vendor_data": "user-123",
  "status": "Approved",
  "workflow_id": "biometric_authentication",
  "liveness": {
    "status": "Approved",
    "method": "ACTIVE_3D",
    "score": 89.92,
    "reference_image": "https://example.com/reference.jpg",
    "video_url": "https://example.com/video.mp4",
    "warnings": []
  },
  "face_match": {
    "status": "Approved",
    "score": 75.43,
    "source_image_session_id": "11111111-2222-3333-4444-555555555555",
    "source_image": "https://example.com/source-image.jpg",
    "target_image": "https://example.com/target-image.jpg",
    "warnings": []
  }
}

Understanding the Results

Overall Authentication Status

"Approved" indicates both liveness detection and face matching were successful
"Declined" suggests either liveness or face matching failed, potentially indicating fraud

Authentication Components

The biometric authentication combines two separate verifications:

Liveness Detection: Verifies that a real person is present (not a photo or video)
Face Matching: Confirms the person is the same as in previous verifications

Both components must pass for the overall authentication to be approved.

For more information about potential warnings during biometric authentication, check our Biometric Authentication Warnings guide.

Security Note

The URLs provided for authentication images and videos are temporary and expire after 60 minutes for enhanced security. Ensure these media resources are handled with appropriate security measures and are not shared publicly. As a best practice, your application should only store the verification status and confidence scores, minimizing the amount of biometric data retained on your servers.

How it Works Warnings