API Reference

POST /ocr/verify

Extract data from uploaded documents and compare against declared personal information.

Authentication: API key (secret)

Request

POST /ocr/verify
Authorization: Bearer oat_your_secret_key
Content-Type: multipart/form-data

Field	Type	Required	Description
`nom`	string	Yes	Declared family name
`prenom`	string	Yes	Declared first name(s)
`date_naissance`	string	Yes	Date of birth (`DD/MM/YYYY` or `YYYY-MM-DD`)
`lieu_naissance`	string	No	Place of birth
`adresse_postale`	string	Yes	Full postal address with postal code and city
`documents`	File[]	Yes	One or more document files (`pdf`, `png`, `jpg`, `jpeg`; max 20MB each)
`documents_metadata`	string	No	JSON array of document type/category hints
`always_ocr`	string	No	`"true"` or `"1"` to always run OCR in parallel with 2D-DOC (default: only if fields missing)

Document metadata

When provided, documents_metadata is a JSON string describing each uploaded file. The array order must match the documents files order.

[
  { "type": "cni", "category": "identity" },
  { "type": "facture_energie", "category": "address" }
]

Document types: cni, passport, permis_de_conduire, facture_energie, avis_imposition, quittance_loyer, attestation_hebergement, other

Categories: identity, address

If metadata is omitted, the system infers types from file names (e.g., a file named customer_id.jpg is treated as an identity document).

Response

{
  "overallScore": 0.92,
  "overallResult": "pass",
  "processingTimeMs": 3420,
  "fieldResults": [
    {
      "field": "nom",
      "declaredValue": "DUPONT",
      "bestExtractedValue": "DUPONT",
      "bestSourceDocument": 0,
      "bestTrustTier": "ocr",
      "matchType": "exact",
      "confidence": 1.0,
      "flags": []
    },
    {
      "field": "prenom",
      "declaredValue": "Jean",
      "bestExtractedValue": "Jean Pierre",
      "bestSourceDocument": 0,
      "bestTrustTier": "ocr",
      "matchType": "normalized",
      "confidence": 0.9,
      "flags": []
    },
    {
      "field": "date_naissance",
      "declaredValue": "05/07/1990",
      "bestExtractedValue": "05/07/1990",
      "bestSourceDocument": 0,
      "bestTrustTier": "ocr",
      "matchType": "exact",
      "confidence": 1.0,
      "flags": []
    },
    {
      "field": "adresse_postale",
      "declaredValue": "10 rue des Lilas 75001 Paris",
      "bestExtractedValue": "10 RUE DES LILAS 75001 PARIS",
      "bestSourceDocument": 1,
      "bestTrustTier": "2ddoc_verified",
      "matchType": "exact",
      "confidence": 1.0,
      "flags": []
    }
  ],
  "crossDocumentChecks": [
    {
      "field": "nom",
      "documents": [
        { "documentIndex": 0, "value": "DUPONT", "trustTier": "ocr" },
        { "documentIndex": 1, "value": "MR ET MME DUPONT MARTIN", "trustTier": "2ddoc_verified" }
      ],
      "consistent": true,
      "note": "Values overlap (containment match)"
    }
  ],
  "documentExtractions": [
    {
      "documentIndex": 0,
      "fileName": "customer_id.pdf",
      "documentType": "cni",
      "documentCategory": "identity",
      "trustTier": "ocr",
      "extractedFields": {
        "nom": "DUPONT",
        "prenom": "Jean Pierre",
        "date_naissance": "05/07/1990",
        "lieu_naissance": "PARIS"
      },
      "extractionMethod": "ocr",
      "extractionDurationMs": 1520
    },
    {
      "documentIndex": 1,
      "fileName": "customer_proof_of_address.pdf",
      "documentType": "facture_energie",
      "documentCategory": "address",
      "trustTier": "2ddoc_verified",
      "extractedFields": {
        "nom": "MR ET MME DUPONT MARTIN",
        "adresse_postale": "10 RUE DES LILAS 75001 PARIS"
      },
      "extractionMethod": "2ddoc",
      "extractionDurationMs": 480,
      "twodocResult": {
        "status": "valid",
        "signatureValid": true,
        "issuer": "Utility Provider",
        "documentType": "Justificatif de domicile"
      }
    }
  ],
  "flags": []
}

Response fields

Field	Type	Description
`overallScore`	number	Weighted confidence score (0-1)
`overallResult`	string	`pass`, `review`, or `fail`
`processingTimeMs`	number	Total processing time in milliseconds
`fieldResults`	array	Per-field comparison results
`crossDocumentChecks`	array	Cross-document consistency checks
`documentExtractions`	array	Raw extraction results per document
`flags`	array	Aggregated flags across all fields

Field result

Field	Type	Description
`field`	string	Field name (`nom`, `prenom`, `date_naissance`, `lieu_naissance`, `adresse_postale`)
`declaredValue`	string	Value provided in the request
`bestExtractedValue`	string\|null	Best value found across all documents
`bestSourceDocument`	number\|null	Index of the document the value came from
`bestTrustTier`	string\|null	Trust tier of the source document
`matchType`	string	`exact`, `normalized`, `partial`, `mismatch`, or `not_available`
`confidence`	number	Match confidence (0-1)
`flags`	array	Flags specific to this field

Trust tiers

Tier	Description
`2ddoc_verified`	Data extracted from a cryptographically signed 2D-DOC barcode
`ocr`	Data extracted by OCR

A vision_only tier value is reserved in the schema but is not emitted by the current pipeline.

Examples

cURL

curl -X POST https://api.verifiables.com/ocr/verify \
  -H "Authorization: Bearer oat_your_secret_key" \
  -F "nom=DUPONT" \
  -F "prenom=Jean" \
  -F "date_naissance=05/07/1990" \
  -F "lieu_naissance=Paris" \
  -F "adresse_postale=10 rue des Lilas 75001 Paris" \
  -F "documents=@customer_id.jpg" \
  -F "documents=@customer_proof_of_address.pdf" \
  -F 'documents_metadata=[{"type":"permis_de_conduire","category":"identity"},{"type":"facture_energie","category":"address"}]' \
  -F "always_ocr=true"

Date DD/MM swap detection

When the declared date of birth has the day and month swapped compared to the documents, the response includes a specific flag:

{
  "overallScore": 0.56,
  "overallResult": "review",
  "fieldResults": [
    {
      "field": "date_naissance",
      "declaredValue": "07/05/1990",
      "bestExtractedValue": "05/07/1990",
      "matchType": "mismatch",
      "confidence": 0.0,
      "flags": [
        {
          "type": "date_dd_mm_swap",
          "message": "Possible DD/MM swap: declared 07/05/1990 but document shows 05/07/1990",
          "details": { "declared": "07/05/1990", "extracted": "05/07/1990" }
        }
      ]
    }
  ],
  "flags": [
    {
      "type": "date_dd_mm_swap",
      "message": "Possible DD/MM swap: declared 07/05/1990 but document shows 05/07/1990"
    },
    {
      "type": "declared_vs_docs_mismatch",
      "message": "Documents agree on \"date_naissance\" but differ from declared value",
      "details": { "declared": "07/05/1990", "documentsAgreeOn": "05/07/1990" }
    }
  ]
}

Spelling discrepancy

When a name is close but not identical (common with double letters or accents):

{
  "field": "nom",
  "declaredValue": "MARTIN",
  "bestExtractedValue": "MARTNI",
  "matchType": "partial",
  "confidence": 0.8,
  "flags": [
    {
      "type": "spelling_close",
      "message": "Close spelling: \"MARTIN\" vs \"MARTNI\" (edit distance: 1)",
      "details": { "declared": "MARTIN", "extracted": "MARTNI", "editDistance": 1 }
    }
  ]
}

On this page