Skip to main content
Our face match 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. We also have a standalone Face Match API to compare any two face image you want.

​
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_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;
    }[];
  }
}

​
Sample Response

{
  "face_match": {
    "status": "In Review",
    "score": 65.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": [
      {
        "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."
      }
    ]
  }
}
For more information about potential warnings during the face matching process, check our Face Match Warnings guide.

​
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.