Facial Similarity Report

Our facial recognition process compares the live image or video of the user with the portrait extracted from their identity document. This comparison ensures that the person presenting the document is indeed the document's owner.

Report Structure

The facial similarity report returns a JSON object with a root-level face_match object containing all verification results.

Core Response Fields

interface FaceMatchVerificationResponse {
  face_match: {
    status: 'Approved' | 'Rejected' | 'In Review' | 'Not Finished';
    score: number;  // Range: 0-100
    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

Status Fields

• status: Overall verification status
• score: Normalized similarity score between live image and document photo (Range: 0-100)

Media References

• source_image: HTTPS URL to the portrait extracted from ID document (JPG, max 1920x1080)
• target_image: HTTPS URL to the best frame from verification (JPG, min 720p)

Risk Assessment

• warnings: Array of detected risks and warnings:
  • risk: The specific risk identified (e.g., "LOW_FACE_MATCH_SIMILARITY")
  • additional_data: Any supplementary information related to the warning (when available)
  • log_type: Classification of the warning (Options: "information", "warning", "error")
  • short_description: Brief explanation of the detected issue
  • long_description: Detailed explanation of the risk and its implications

Sample Response

{
  "face_match": {
    "status": "In Review",
    "score": 65.43,
    "source_image": "https://example.com/source-image.jpg",
    "target_image": "https://example.com/target-image.jpg",
    "warnings": [
      {
        "risk": "LOW_FACE_MATCH_SIMILARITY",
        "additional_data": null,
        "log_type": "warning",
        "short_description": "Low face match similarity",
        "long_description": "The facial features of the provided image don't closely match the reference image, suggesting a potential identity mismatch."
      }
    ]
  }
}

Understanding the Results

Face Match Status

• "Approved" indicates a successful match between the live image and the document portrait.
• "Rejected" suggests a significant discrepancy, potentially indicating fraud.
• "In Review" may require manual review or additional verification steps.

Face Match Similarity

• Scores typically range from 0 to 100, with higher scores indicating greater similarity.
• The threshold for approval can be customized based on your risk tolerance.
• Scores below your configured thresholds may trigger manual review or rejection.

Security Note

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