Scan Document

Upload a document file to detect its 2D-DOC barcodes, then parse and verify each one. A file may hold several: a rental file carries a tax notice, an identity card and a second notice.

Request

POST /2ddoc/scan
Authorization: Bearer oat_your_publishable_key
Content-Type: multipart/form-data

file: <PDF or image file>

Supported formats

PDF documents (with or without text layer)
Images: png, jpg, jpeg, gif, webp, bmp, tiff

Maximum file size: 20MB.

A file of several pages can take tens of seconds: send Prefer: respond-async (or the form field async=true) to get a job at once instead, see asynchronous processing.

The response carries found, then the first 2D-DOC of the file: the page it was found on and its full verify response spread at the top level. documents lists every 2D-DOC of the file in page order, the first one included, each with its page and its verify response. A PDF is read up to its 20th page.

Each 2D-DOC verified counts as one verification: a file with three codes counts three.

{
  "found": true,
  "page": 1,
  "status": "valid",
  "verification": {
    "SIGNATURE": [
      { "status": "✅", "check": "Signature is cryptographically valid" }
    ],
    "CERTIFICATE": [
      { "status": "✅", "check": "Certificate found: Certigna" }
    ],
    "DOCUMENT": [
      { "status": "✅", "check": "Document type: Facture" }
    ],
    "VALIDATION": [
      { "status": "✅", "check": "Document structure and field values are valid" }
    ]
  },
  "document": {
    "header": { "formatVersion": "v1", "version": "04", "caId": "FR04", "certificateId": "0001", "documentTypeCode": "01", "documentEmissionDate": "2026-01-15T00:00:00.000Z", "signatureDate": "2026-01-15T00:00:00.000Z", "signatureDateFormatted": "15/01/2026" },
    "documentType": "Facture",
    "fields": { "invoice": [ { "id": "10", "value": "MME/SPECIMEN/NATACHA", "rawValue": "MME/SPECIMEN/NATACHA", "truncated": false, "label": "Nom du bénéficiaire", "category": "invoice" } ] },
    "data": { "beneficiary_name": "MME/SPECIMEN/NATACHA" }
  },
  "certificate": { "providerTradeName": "Certigna", "trusted": true },
  "documents": [
    { "page": 1, "status": "valid", "verification": { "…": "…" }, "document": { "…": "…" }, "certificate": { "…": "…" } }
  ]
}

Processing pipeline

Detection: each page of a PDF, or the image, goes through a barcode detector that locates the codes
Reading: each zone is read (DataMatrix, QR code or Aztec), from a crop rendered at a resolution suited to it
Verification: each 2D-DOC read is parsed and verified (same as /2ddoc/verify)

A code that is not a 2D-DOC

When the file's only code is not a 2D-DOC (the payment code of a tax notice, a link QR code), the response is a failed verdict. It gives the code's symbology, never its content, and counts as one verification like any other verdict.

{
  "found": true,
  "notTwoDDoc": true,
  "status": "failed",
  "symbology": "datamatrix",
  "error": "The code read is not a 2D-DOC: it has no 2D-DOC header and no signature",
  "verification": {
    "DOCUMENT": [{ "status": "❌", "check": "The code read is not a 2D-DOC (no DC header, no signature)" }]
  },
  "documents": [{ "notTwoDDoc": true, "status": "failed", "symbology": "datamatrix", "...": "same as above" }]
}

A file that holds a 2D-DOC and another code (the notice's 2D-DOC and its payment code) returns the 2D-DOC alone; the other code is ignored.

No barcode found

{
  "found": false,
  "error": "No 2D-DOC barcode found in the document"
}

This can happen if:

The document doesn't contain a 2D-DOC barcode
The image quality is too low for barcode detection
The barcode is obscured or damaged

Errors

Status	Condition
`400`	Missing `file` field, or the file fails size/extension validation
`503`	The scanner binaries are unavailable on the server: `dmtxread` (libdmtx) for barcode detection, or `pdftoppm` (poppler-utils) for PDF input

Check binary availability with GET /2ddoc/status.