API Reference

One endpoint. Two images. Instant identity verification.

Verify Identity

POST /api/verify

Submit a government-issued ID document and a selfie photo. Veriproof's AI agents will extract document data, match the face, and return a pass/fail verdict with confidence scores.

Request Body

Field	Type		Description
document_image	string	required	Base64-encoded image of a government-issued ID (passport, driver's license, national ID)
selfie_image	string	required	Base64-encoded selfie/live photo of the person being verified

Example Request

{
  "document_image": "/9j/4AAQSkZJRgABAQ...",
  "selfie_image": "/9j/4AAQSkZJRgABAQ..."
}

Response

{
  "id": "a1b2c3d4-e5f6-...",
  "status": "completed",
  "verdict": "pass",
  "confidence_score": 0.92,
  "document": {
    "type": "passport",
    "name": "John Smith",
    "date_of_birth": "1990-05-15",
    "id_number": "AB1234567",
    "country": "USA",
    "expiry_date": "2028-05-15"
  },
  "face_match": {
    "match": true,
    "score": 0.95
  },
  "risk_signals": [],
  "processing_time_ms": 2340,
  "created_at": "2026-04-30T06:00:00.000Z"
}

Response Fields

Field	Type	Description
id	uuid	Unique verification ID
verdict	string	`"pass"` or `"fail"`
confidence_score	number	0.0 to 1.0 — weighted combination of document quality and face match
document	object	Extracted document data (type, name, DOB, ID number, country, expiry)
face_match	object	Face comparison result: `match` (boolean) and `score` (0-1)
risk_signals	array	List of detected risk factors (expired doc, low quality, face mismatch, etc.)
processing_time_ms	number	Total processing time in milliseconds

Verdict Logic

The verification fails if any of these conditions are met:

Document confidence score below 0.5
Document is not a valid government ID
Document appears altered or tampered
Document is expired
Face match score below 0.7
Presentation attack detected (photo of a photo)
AI analysis fails or returns an error

Error Responses

400 — Missing Fields

{ "error": "missing_fields", "message": "Both document_image and selfie_image are required (base64-encoded)." }

400 — Invalid Images

{ "error": "invalid_images", "message": "Images appear too small. Provide clear, high-resolution photos." }

500 — Verification Failed

{ "error": "verification_failed", "message": "An error occurred during verification. Please try again." }