Skip to main content

​
Endpoint

POST /loopos_ai_id_validator Analyzes ID document images to extract document type, number, name, and expiry date, and validates document authenticity.

​
Request

​
language
string
default:"PT-PT"
Language code for the request
​
images
array
required
List of image URLs or base64 data URLs (typically front and back of document)
​
agent_specific
object
required
ID validation specific parameters:
  • doc_type (string, required): Document types to accept, comma-separated (e.g., “passport,id-card”)
  • name (string, optional): Expected name on document (if nil, no name validation performed)
  • number (string, optional): Expected document number (if nil, no number validation performed)
  • validity (boolean, optional): Should verify if validity is in the future (if false, no validity validation performed)
​
loopos_core_context
string
Business context for the AI agent
​
session_extra_data
object
Additional session metadata

​
Response

​
status
string
required
Overall result: “OK”, “ERROR_IMAGE_QUALITY”, or “ERROR_VALIDATION”
​
message
string
Human-readable message (localized)
​
doc_type
string
Canonical document type detected (e.g., “dni-es”, “passport”, “cc-pt”)
​
number
string
Extracted document number (normalized)
​
name
string
Extracted holder name (uppercase, no diacritics if normalized)
​
expiry
string
Expiry date in ISO YYYY-MM-DD format if found
​
item_id
string
Document ID in docType_country_number format
​
ocr_confidence
number
Heuristic overall OCR confidence (0-1)
​
reasoning
string
required
Explanation of the validation process

​
Example Request

{
  "language": "PT-PT",
  "images": ["data:image/jpeg;base64,..."],
  "agent_specific": {
    "doc_type": "passport,id-card",
    "name": "John Doe",
    "number": "123456789",
    "validity": true
  }
}

​
Example Response

{
  "status": "OK",
  "message": "Document validated successfully",
  "doc_type": "passport",
  "number": "123456789",
  "name": "JOHN DOE",
  "expiry": "2025-12-31",
  "item_id": "passport_pt_123456789",
  "ocr_confidence": 0.95,
  "reasoning": "Document validated successfully..."
}

​
Status Values

  • OK: Document is legible and valid
  • ERROR_IMAGE_QUALITY: Image is illegible or poor quality
  • ERROR_VALIDATION: Image is legible but validation failed (name/number/validity mismatch)