Skip to main content
Our Liveness Detection process provides comprehensive insights into the verification process, helping you understand the security assessment and potential risks associated with each verification attempt.

​
Report Structure

The liveness detection report is returned as a JSON object containing a liveness object with the following key sections:
  • Liveness Status: Overall verification status and confidence score
  • Media References: URLs to captured images and videos
  • Method Details: Information about the liveness detection method used
  • Risk Assessment: Warnings and potential security issues detected
  • Verification Metadata: Additional verification details and timestamps

​
Core Response Fields

interface LivenessVerificationResponse {
  liveness: {
    status: 'Approved' | 'Declined' | 'In Review' | 'Not Finished';
    method: 'ACTIVE_3D' | 'FLASHING' | 'PASSIVE';
    score: number;
    reference_image: string;       // Temporary URL
    video_url: string;            // Temporary URL
    age_estimation: number | null;       // Age estimation in years for the target image
    matches: {
      session_id: string;
      session_number: int;
      similarity_percentage: number;           // Range: 0-100
      vendor_data: string | null;   // Your reference data from the original verification
      verification_date: string;    // ISO 8601 timestamp
      user_details: {
        name: string;
        document_type: string;
        document_number: string;    // Partially masked for security
      };
      match_image_url: string;      // Temporary URL
      status: 'Approved' | 'In Review' | 'Declined';      // Status for the matched session
      is_blocklisted: bool;      // Whether the face from the matched session is blocklisted
    }[];
    warnings: {
      risk: string;
      additional_data: string | null;
      log_type: 'information' | 'warning' | 'error';
      short_description: string;
      long_description: string;
    }[];
  }
}

​
Sample JSON Response

{
  "liveness": {
    "status": "Approved",
    "method": "ACTIVE_3D",
    "score": 89.92,
    "reference_image": "https://example.com/reference.jpg",
    "video_url": "https://example.com/video.mp4",
    "age_estimation": 24.3,
    "matches": [
      {
        "session_id": "session-789012",
        "session_number": 123,
        "similarity_percentage": 96.8,
        "vendor_data": "user-555",
        "verification_date": "2024-07-15T10:23:45.123Z",
        "user_details": {
          "name": "John Smith",
          "document_type": "Passport",
          "document_number": "XXXXXXXX"
        },
        "match_image_url": "https://example.com/face/789012.jpg",
        "status": "Approved",
        "is_blocklisted": false
      },
      {
        "session_id": "session-345678",
        "session_number": 1233,
        "similarity_percentage": 82.4,
        "vendor_data": "user-777",
        "verification_date": "2024-06-20T15:17:32.789Z",
        "user_details": {
          "name": "John A Smith",
          "document_type": "Driver's License",
          "document_number": "XXXXXXXX"
        },
        "match_image_url": "https://example.com/face/345678.jpg",
        "status": "Approved",
        "is_blocklisted": false
      },
      {
        "session_id": "session-234567",
        "session_number": 4133,
        "similarity_percentage": 71.2,
        "vendor_data": "user-999",
        "verification_date": "2024-05-10T09:45:22.456Z",
        "user_details": {
          "name": "Jonathan Smith",
          "document_type": "ID Card",
          "document_number": "XXXXXXXX"
        },
        "match_image_url": "https://example.com/face/234567.jpg",
        "status": "Declined",
        "is_blocklisted": true
      }
    ],
    "warnings": [
      {
        "risk": "LOW_LIVENESS_SCORE",
        "additional_data": null,
        "log_type": "information",
        "short_description": "Low liveness score",
        "long_description": "The liveness check resulted in a low score, indicating potential use of non-live facial representations or poor-quality biometric data."
      }
    ]
  }
}
For more information about potential warnings during the liveness detection process, check our Liveness Detection Warnings guide.

​
Security Note

The URLs provided for liveness verification 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 score, minimizing the amount of biometric data retained on your servers.