API Documentation — ID OCR Engine

POST /api/extract

Reads one document. Locates and straightens the card, identifies the document type, extracts the fields, crops the portrait photograph, and checks the result against the document’s own internal validation. Send it as multipart/form-data.

Parameter	Type	Required	Description
`file`	Multipart file	Yes	Scanned document as JPEG, PNG or PDF. 300 DPI or better is recommended.

Example request

curl -X POST http://127.0.0.1:8000/api/extract \
  -F "[email protected]"

200 — UK driving licence

{
  "doc_type": "driving_licence",
  "accept": true,
  "checks_passed": 6,
  "checks_total": 6,
  "fields": {
    "Surname": "TAYLOR",
    "Given Names": "ALEX JAMES",
    "Title": "MR",
    "Date of Birth": "01.01.1990",
    "Date of Issue": "01.01.2020",
    "Date of Expiry": "01.01.2030",
    "Document Number": "TAYLO901011AJ9AB",
    "Address": "1 EXAMPLE STREET, LONDON, E1 1AA",
    "Address Street": "1 EXAMPLE STREET",
    "Address City": "LONDON",
    "Address Postal Code": "E1 1AA",
    "DL Class": "AM/B/f/k/q",
    "Card issuance number": "01",
    "Place of Birth": "UNITED KINGDOM",
    "Authority": "DVLA"
  },
  "confidences": { "Surname": 0.99 },
  "face": "data:image/jpeg;base64,...",
  "ms": 1600
}

Field	Description
`doc_type`	One of `driving_licence`, `passport`, `id_card` or `unknown`.
`accept`	Whether the document passed its own validation. See below.
`checks_passed` / `checks_total`	How many validation checks ran, and how many agreed.
`fields`	The extracted values. Keys not present on the document are omitted.
`confidences`	Per-field recognition confidence, 0 to 1.
`face`	Cropped portrait photograph as a base64 data URL, or `null`.
`ms`	Processing time in milliseconds.

The accept flag

Every document is checked against itself. A UK licence number encodes the holder’s own surname and date of birth, and the machine-readable zone on a passport or ID card carries check digits. No external lookup is involved.

Value	Meaning	What to do
`true`	The document’s own checks agree with what was read.	Safe to store.
`false`	The checks disagree with what was read.	Route to a person before storing.

Passports and ID cards

These are read from the machine-readable zone — the two or three lines of monospaced text at the foot of the document. It is an international standard (ICAO 9303) carrying its own check digits, so the values below are verified character by character rather than merely recognised. doc_type is passport for a passport book and id_card for an ID card.

200 — passport

{
  "doc_type": "passport",
  "accept": true,
  "checks_passed": 5,
  "checks_total": 5,
  "fields": {
    "Surname": "ERIKSSON",
    "Given Names": "ANNA MARIA",
    "Full Name": "ERIKSSON ANNA MARIA",
    "Document Number": "L898902C3",
    "Personal Number": "ZE184226B",
    "Date of Birth": "1974-08-12",
    "Date of Expiry": "2012-04-15",
    "Sex": "F",
    "Nationality": "UTO",
    "Nationality Code": "UTO",
    "Issuing State Code": "UTO",
    "Document Class Code": "P"
  },
  "face": "data:image/jpeg;base64,...",
  "ms": 1500
}

Field	Description
`Surname`, `Given Names`	As printed in the machine-readable zone.
`Full Name`	Surname followed by given names.
`Document Number`	Passport or card number.
`Personal Number`	National identifier, where the issuing country prints one.
`Date of Birth`, `Date of Expiry`	ISO format, `YYYY-MM-DD`.
`Sex`	`M`, `F` or `X`.
`Nationality`, `Nationality Code`	Three-letter country code, e.g. `GBR`.
`Issuing State Code`	Three-letter code of the issuing country.
`Document Class Code`	`P` for passport, `ID` for an identity card.

Date of issue, place of birth and issuing authority are not returned for these documents. They are not part of the machine-readable zone, so they cannot be read from it. Do not treat their absence as a failure.

Date formats differ by document

Dates are returned as they are carried on the document, so the format is not the same for every type. Parse according to doc_type.

Document	Format	Example
Driving licence	`DD.MM.YYYY`	`01.01.1990`
Passport, ID card	`YYYY-MM-DD`	`1974-08-12`

Response codes

Code	Meaning
`200`	Document processed.
`400`	The upload could not be read as an image.
`422`	The document could not be processed.

Error response

{ "error": "Could not read that image." }

GET /health

Liveness check. Returns 200 once the model is loaded and the service is ready.

{ "status": "ok" }

GET /docs

Interactive API reference, generated from the service itself. Requests can be sent directly from the browser.

Integration Guide