Didit Docs

Face Search Report

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;
      similarity: 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
    }[];
    warnings: {
      risk: string;
      additional_data: string | null;
      log_type: 'information' | 'warning' | 'error';
      short_description: string;
      long_description: string;
    }[];
  }
}

Response Fields

Status Fields

status: Overall search status indicating if the process is complete
total_matches: Number of matches found that meet the configured threshold

Matches Array

Each match in the matches array contains:

session_id: Unique identifier of the matching verification session
similarity: Normalized similarity score between search image and matched image (Range: 0-100)
vendor_data: Your custom reference data from the original verification session
verification_date: When the matched user was verified
user_details: Basic information about the matched user
match_image_url: Temporary URL to the matched face image

Risk Assessment

warnings: Array of detected risks and warnings:
- risk: The specific risk identified
- additional_data: Any supplementary information related to the warning
- 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_search": {
    "status": "Approved",
    "total_matches": 3,
    "matches": [
      {
        "session_id": "session-789012",
        "similarity": 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"
      },
      {
        "session_id": "session-345678",
        "similarity": 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"
      },
      {
        "session_id": "session-234567",
        "similarity": 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"
      }
    ],
    "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.

How it Works Warnings