Skip to main content
Our Face Search feature allows you to search for a specific face across all your approved identity verification sessions. This powerful capability helps identify duplicate accounts, prevent fraud, and enhance your security measures.

​
Report Structure

The face search report returns a JSON object with a root-level face_search object containing all search results.

​
Core Response Fields

interface FaceSearchResponse {
  face_search: {
    status: 'Approved' | 'In Review' | 'Declined';
    total_matches: number;
    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
    }[];
   	user_image: {
      entities: [
        {
          age: string, 
         	bbox: int[];      // Position of the face. For example, [40, 40, 120, 120]
          confidence: float;       // Range: 0-1
          gender: 'male' | 'female' | null;
        }
      ],
      best_angle: 0 | 90 | 180 | 270;      // If rotate_image enabled, this is the rotation performed
    },
    warnings: {
      risk: string;
      additional_data: string | null;
      log_type: 'information' | 'warning' | 'error';
      short_description: string;
      long_description: string;
    }[];
  }
}

​
Sample Response

{
  "face_search": {
    "status": "Approved",
    "total_matches": 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_QUALITY_SEARCH_IMAGE",
        "additional_data": null,
        "log_type": "information",
        "short_description": "Low quality search image",
        "long_description": "The image used for searching has low quality, which may reduce the accuracy of matching results."
      }
    ],
  }
}
For more information about potential warnings during the face search process, check our Face Search 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 scores, minimizing the amount of biometric data retained on your servers.