API reference

Authenticate from your server.

API access is available on request. Use your key only in your server application, never in browser code, mobile client bundles, URLs or public repositories.

Missing or incorrect credentials return 401 unauthorized. Keys are matched exactly. After activation, you receive the separate base URL. Configure MRZ_BASE_URL and protected MRZ_API_KEY on your server. The /v1/mrz route on this website is currently disabled (HTTP 404).

Send one image as Base64 JSON.

Set Content-Type: application/json and send exactly the image_base64 field. Encode the image bytes using standard Base64.

{
  "image_base64": "BASE64_IMAGE"
}

Multipart remains supported.

Existing integrations can continue to send the image in multipart field file. Let the HTTP client generate the Content-Type with its boundary. Recognition and response semantics are the same for both input formats.

curl "${MRZ_BASE_URL}/v1/mrz?include_crop=false" \
  --header "Authorization: Bearer $MRZ_API_KEY" \
  --form 'file=@document.jpg' 

POST /v1/mrz

HTTP 200 returns a MRZResponse object. Each document remains a separate candidate.

Result states

Complete response example

Illustrative example using public ICAO Utopia data. Image bytes are replaced with BASE64_JPEG; timing and version values illustrate the type and are not performance claims.

{
  "image": {
    "width": 1200,
    "height": 760,
    "coordinate_space": "exif_oriented_pixels"
  },
  "documents": [
    {
      "status": "recognized",
      "format": "TD3",
      "raw_mrz": [
        "P<UTOERIKSSON<<ANNA<MARIA<<<<<<<<<<<<<<<<<<<",
        "L898902C36UTO7408122F1204159ZE184226B<<<<<10"
      ],
      "mrz": [
        "P<UTOERIKSSON<<ANNA<MARIA<<<<<<<<<<<<<<<<<<<",
        "L898902C36UTO7408122F1204159ZE184226B<<<<<10"
      ],
      "fields": {
        "document_code": "P<",
        "issuing_state": "UTO",
        "document_number_raw": "L898902C3",
        "nationality": "UTO",
        "date_of_birth": "740812",
        "sex": "F",
        "date_of_expiry": "120415",
        "optional_data": "ZE184226B<<<<<",
        "names_raw": "ERIKSSON<<ANNA<MARIA<<<<<<<<<<<<<<<<<<<",
        "document_number": "L898902C3",
        "document_number_extended": false,
        "surname_raw": "ERIKSSON",
        "given_names_raw": "ANNA<MARIA",
        "surname": "ERIKSSON",
        "given_names": "ANNA MARIA"
      },
      "checks": {
        "date_of_birth": {
          "expected": "2",
          "actual": "2",
          "valid": true,
          "applicable": true
        },
        "date_of_expiry": {
          "expected": "9",
          "actual": "9",
          "valid": true,
          "applicable": true
        },
        "optional_data": {
          "expected": "1",
          "actual": "1",
          "valid": true,
          "applicable": true
        },
        "document_number": {
          "expected": "6",
          "actual": "6",
          "valid": true,
          "applicable": true
        },
        "composite": {
          "expected": "0",
          "actual": "0",
          "valid": true,
          "applicable": true
        }
      },
      "corrections": [],
      "errors": [],
      "mrz_quad": [
        [
          60.63999938964844,
          516.3800048828125
        ],
        [
          1112.280029296875,
          515.219970703125
        ],
        [
          1112.6600341796875,
          601.4600219726562
        ],
        [
          60.790000915527344,
          602.9500122070312
        ]
      ],
      "recognition_score": 0.9833,
      "recognition_method": "neural_mrz_casefold_aspect0.7+neural_mrz_casefold",
      "document_quad": [
        [
          11.5600004196167,
          3.5999999046325684
        ],
        [
          1185.4300537109375,
          9.420000076293945
        ],
        [
          1185.760009765625,
          756.9400024414062
        ],
        [
          9.619999885559082,
          754.3699951171875
        ]
      ],
      "crop_quad": [
        [
          11.559963226318358,
          3.598575592041015
        ],
        [
          1185.4285889897849,
          9.422903061521222
        ],
        [
          1185.759399282995,
          756.9421386655698
        ],
        [
          9.615039825346546,
          754.3733520866444
        ]
      ],
      "document_score": 0.9992,
      "crop_basis": "document",
      "association_basis": null,
      "recognition_retry": null,
      "crop_jpeg_base64": "BASE64_JPEG"
    }
  ],
  "timed_out": false,
  "processing_ms": 125.5,
  "engine_version": "0.1.6"
}

Document object: all public fields

Extracted fields

Interpret check digits correctly

{"expected":"6","actual":"6","valid":true,"applicable":true}

expected is the calculated digit, actual is the observed digit; either can be null. Only applicable=true and valid=true mean an applicable check passed. Missing or non-applicable checks do not count as passed. Check names: document_number, date_of_birth, date_of_expiry, optional_data and composite.

Handle diagnostics and multiple documents.

Each candidate carries its diagnostics in errors. Also inspect checks, corrections and, when present, recognition_retry. A recognized status does not replace these checks.

Document diagnostics

The current engine can return the following diagnostic groups. Failed check digits also appear as checksum_<name> in errors. Preserve unknown future codes and route them to review instead of assuming success.

Multiple candidates remain separate.

documents contains every candidate, including those with uncertain or no_mrz. The API does not select one flat result or merge fields. If your application expects exactly one document, check the count and candidates explicitly. Ask for a separate document image or provide manual selection when ambiguous. documents: [] means no candidate was found.

HTTP errors and concrete next steps.

Request and service failures use HTTP 4xx/5xx. The table covers current engine mappings, including shared decoder diagnostics. Not every diagnostic code can occur for every format.

Distinguish error envelopes

{"error":"invalid_base64"}

{"error":"processing_timeout","timed_out":true,"documents":[]}

Proxy errors may return a simple object such as {"error":"request_failed"}. An unknown URL can return HTTP 404 with text rather than JSON. Always check status and Content-Type before reading a success model. Handle new diagnostic codes defensively.

A reliable flow for your application.

1. Check the HTTP response

   4xx: correct input or credentials. 503: honour Retry-After. 500/502/504: retry a limited number of times with a pause. Catch network failures and non-JSON responses separately.

2. Check the processing outcome

   timed_out=false, intended candidate present, and documents[].status=recognized. Explicitly check candidate count and association. Do not import partial fields from negative outcomes.

3. Validate warnings and fields

   Evaluate checks, corrections, raw readings and association evidence. Validate required fields, date assumptions, age and expiry against your business rules. Do not fill missing fields with guesses.

4. Import or route to review

   Import only after your acceptance criteria are met. Route uncertain, ambiguous or incomplete results to a visible review process. Never declare documents authentic because check digits pass.

Decode image outputs from Base64 and validate JPEG format and dimensions before further processing. Create a display data URL only in your own UI. Log technical status/error codes rather than document images, full responses or API keys.

Formats and limits

AI image enhancement is a separate extension on request. This interface has no standard parameter to activate “Enhance Output Image with AI”.

Public website demo

Consent and training storage in the demo

Selecting files or samples, dropping files or activating the camera starts transmission after the visible storage notice. The interface sends X-Training-Consent: training-v3; training-v1 and training-v2 remain accepted for older clients. The header identifies the notice version.

Original images and complete results are stored encrypted for 30 days from upload for training and quality improvement, then deleted automatically. You can request earlier deletion at info@oasisscan.de using your upload ID. This storage applies only to the public demo.

X-Training-Upload-ID provides the ID of an accepted storage record. An upload may already be stored even when recognition fails; do not automatically repeat it in that case. Cancelling or resetting does not delete stored data.

Demo-specific errors: 422 training_consent_required means the notice marker is missing or unsupported; 503 training_storage_unavailable means secure storage is temporarily unavailable. Processing does not silently continue without storage. 503 service_busy without an upload ID can be retried a limited number of times after Retry-After. Browser batch mode uses up to four concurrent single-image requests and shows a status and upload ID per file. See the privacy notice.