Passport Verification API

A REST API for verifying passport authenticity and face matching using Google Gemini AI and computer vision technologies.

Table of Contents

• Overview
• Features
• File Structure
• Installation
• Configuration
• How It Works
• API Endpoints
• Authentication
• Response Examples
• Services
• Helpers
• Error Handling

Overview

This API provides passport verification capabilities using two complementary approaches:

1. Google Gemini AI for document verification and face comparison
2. PassportEye + DeepFace for traditional computer vision verification

The system processes passport images and user facial images to verify document authenticity and identity matching without storing any data.

Features

• Passport document validation using MRZ (Machine Readable Zone) data extraction
• Face matching between passport photo and user-provided facial image
• Dual verification approach (AI and traditional computer vision)
• Confidence scoring for verification results
• Detailed extraction of passport information
• Tampering detection with specific suspicious elements identification
• API key authentication for secure access
• No data persistence (privacy-focused)

File Structure

passport-verification-api/
├── main.py                     # Main application entry point
├── requirements.txt            # Project dependencies
├── api/
│   ├── config/
│   │   ├── app_settings.py     # Application configuration loader
│   │   └── config.yaml         # Configuration values
│   ├── controller/
│   │   └── passport_verification_controller.py  # API endpoints
│   ├── middleware/
│   │   └── auth_middleware.py  # API key authentication
│   ├── service/
│   │   ├── passport_verification_service.py   # Main verification orchestration
│   │   ├── gemini_service.py                  # Google Gemini integration
│   │   ├── passport_eye_service.py            # PassportEye integration
│   │   └── face_verification_service.py       # DeepFace integration
│   └── helpers/
│       ├── file_helper.py       # Image processing utilities
│       ├── validation_helper.py # Input validation
│       └── response_helper.py   # API response formatting

Installation

1. Clone the repository:

git clone https://github.com/yourusername/passport-verification-api.git
cd passport-verification-api

2. Create a virtual environment:

python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate

3. Install dependencies:

pip install -r requirements.txt
pip install google-generativeai
pip install opencv-python 
pip install pillow 
pip install flask-cores 
pip install pyyaml 
pip install flask 

4. Configure the application (update config.yaml as needed)

5. Run the application:

python main.py

Configuration

The application uses a YAML configuration file located at api/config/config.yaml. Key configuration settings include:

# Server configuration
server:
  ip: "0.0.0.0"
  port: 12345
  debug: true
  appKey: "AB12-CDEF-3456-GHITA"
  ssl: false
  ssl_key: ""
  ssl_cert: ""

# Database configuration
database:
  uri: "sqlite:///app.db"
  track_modifications: false

# Gemini API configuration
gemini:
  api_key: "YOUR_GEMINI_API_KEY"  # Replace with your actual API key
  model: "gemini-2.0-flash"       # Can be changed to other models like "gemini-1.5-pro"
  max_retries: 3
  retry_delay: 2                  # Base delay in seconds (will use exponential backoff)

# API authentication settings
api_auth:
  app_id: "passport-verification-service"
  api_key: "pvs-f47ca88e-3b6f-4d32-a404-82d62f9987e9"  # Replace with your secure API key

Note: While database configuration is present, this application doesn't use persistent storage for privacy reasons.

How It Works

The verification process follows these steps:

1. User uploads passport image and facial image to the API with an authentication API key
2. Images are validated for proper format and quality
3. Passport is processed using:
   • Google Gemini AI for document analysis and data extraction
   • PassportEye for MRZ data extraction
4. Face verification is performed using:
   • DeepFace for biometric comparison
   • Google Gemini AI for secondary face verification
5. Results from both methods are combined for a comprehensive verification score
6. Tampering detection analyzes for suspicious elements, inconsistencies, and potential manipulation
7. API returns detailed verification results with security analysis

API Endpoints

Verify Passport and Face

Endpoint: POST /api/v1/passport/verify

Authentication: API Key (see Authentication)

Content-Type: multipart/form-data

Required Parameters:

• passport_image (file): The passport document image
• face_image (file): The user's facial image for comparison

Supported Image Formats: JPG, JPEG, PNG

Example Request:

curl -X POST \
  http://localhost:12345/api/v1/passport/verify \
  -H "X-API-Key: pvs-f47ca88e-3b6f-4d32-a404-82d62f9987e9" \
  -F "passport_image=@/path/to/passport.jpg" \
  -F "face_image=@/path/to/face.jpg"

Authentication

This API uses API key authentication to secure all endpoints. You must include a valid API key with each request.

API Key Location: The API key can be provided in one of the following ways:

• HTTP Header: X-API-Key: your-api-key
• URL Parameter: ?api_key=your-api-key
• Form Data Field: api_key=your-api-key

Security Notes:

• API keys are defined in the config.yaml file
• The authentication uses constant-time comparison to prevent timing attacks
• Requests without a valid API key will receive a 401 Unauthorized response

Response Examples

Successful Verification

{
  "success": true,
  "message": "Passport verification completed",
  "data": {
    "isValid": true,
    "isTampered": false,
    "confidenceScore": 92.5,
    "extractedData": {
      "documentType": "Passport",
      "countryCode": "USA",
      "passportNumber": "123456789",
      "surname": "SMITH",
      "givenNames": "JOHN MICHAEL",
      "nationality": "UNITED STATES OF AMERICA",
      "dateOfBirth": "1990-01-01",
      "sex": "M",
      "dateOfExpiry": "2030-01-01",
      "mrzData": "P<USASMITH<<JOHN<MICHAEL<<<<<<<<<<<<<<<<<<<<<<..."
    },
    "tamperingDetails": {
      "suspiciousElements": [],
      "inconsistencies": [],
      "potentialManipulation": []
    },
    "faceVerification": {
      "isMatch": true,
      "matchConfidence": 89.3,
      "verificationMethod": "Composite (DeepFace + Gemini)"
    },
    "verificationDetails": {
      "documentVerification": {
        "gemini": {
          "isValid": true,
          "confidence": 95.0,
          "extractedText": "PASSPORT\nType: P\nCountry Code: USA...",
          "analysis": "The document appears to be a valid US passport..."
        },
        "passportEye": {
          "isValid": true,
          "confidence": 90.0,
          "mrzValid": true
        }
      }
    }
  }
}

Failed Verification (Tampered Document)

{
  "success": true,
  "message": "Passport verification completed",
  "data": {
    "isValid": false,
    "isTampered": true,
    "confidenceScore": 35.2,
    "extractedData": {
      "documentType": "Passport",
      "countryCode": "USA",
      "passportNumber": "123456789",
      "surname": "SMITH",
      "givenNames": "JOHN MICHAEL",
      "dateOfBirth": "1990-01-01",
      "sex": "M",
      "dateOfExpiry": "2030-01-01"
    },
    "tamperingDetails": {
      "suspiciousElements": [
        "MRZ data checksum fails validation",
        "Inconsistent typography in name field",
        "Abnormal color pattern around date of birth"
      ],
      "inconsistencies": [
        "Date format differs between visual and MRZ zones",
        "Passport number format doesn't match issuing country standard"
      ],
      "potentialManipulation": [
        "Digital alteration detected in photo area",
        "Possible text manipulation in date field"
      ]
    },
    "faceVerification": {
      "isMatch": false,
      "matchConfidence": 42.8,
      "verificationMethod": "Composite (DeepFace + Gemini)"
    },
    "verificationDetails": {
      "documentVerification": {
        "gemini": {
          "isValid": false,
          "confidence": 45.0,
          "extractedText": "PASSPORT\nType: P\nCountry Code: USA...",
          "analysis": "The document appears to have inconsistencies..."
        },
        "passportEye": {
          "isValid": false,
          "confidence": 25.4,
          "mrzValid": false,
          "error": "Invalid MRZ checksum"
        }
      }
    }
  }
}

Authentication Error

{
  "success": false,
  "message": "Unauthorized: Invalid or missing API key",
  "data": null
}

Error Response (Invalid Input)

{
  "success": false,
  "message": "Both passport_image and face_image are required",
  "data": null
}

Services

PassportVerificationService

The main orchestration service that:

• Coordinates between different verification methods
• Processes uploaded images
• Combines results from multiple verification sources
• Identifies potential document tampering
• Produces a final verification assessment

GeminiService

Integrates with Google Gemini AI to:

• Analyze passport document authenticity
• Extract textual information from passport
• Identify suspicious elements and potential tampering
• Compare facial images for identity verification
• Provide AI-based confidence scoring
• Uses configuration for model selection and parameters

PassportEyeService

Uses the PassportEye library to:

• Read and parse MRZ data from passports
• Validate passport data format and checksums
• Extract structured information from passport

FaceVerificationService

Uses DeepFace to:

• Extract faces from images
• Compare facial biometrics
• Calculate similarity scores
• Determine identity match confidence

Helpers

FileHelper

Provides utilities for:

• Image processing and normalization
• Face extraction from passport images
• Image format conversion and validation

ValidationHelper

Ensures input data correctness by:

• Validating image file formats and sizes
• Checking passport data structure
• Verifying MRZ data integrity

ResponseHelper

Standardizes API responses with:

• Consistent success and error formats
• Proper HTTP status codes
• Detailed error information when needed

Error Handling

The API handles various error scenarios:

• Authentication failures with invalid API keys
• Missing required files or parameters
• Invalid image formats or corrupted files
• Undetectable faces in images
• Unreadable passport MRZ data
• Integration failures with external services
• Document tampering detection

All errors return appropriate HTTP status codes with detailed error messages to facilitate troubleshooting.