Document data capture

Read the fields of an identity document from a photo, to prefill a form that a person then confirms. The photo is encrypted on the device; your backend fetches the fields once, with its secret key.

Who does what

The work is split between your backend and the user’s device, the same way as verification.

A publishable key never receives a field, and a secret key never belongs on a device or in a browser. Start may also be called with a publishable key from a native app; it is not available to browsers (there is no cross-origin access to it), so a web app always starts the capture from its backend and hands the Start response to the page.

Document types

Declare the type when you start. It is a routing hint, never evidence: the issuing country, for example, is read from the document itself. The type codes are frozen; new types are only ever added. Each type must be enabled for your account.

The flow

1. Start

POST /v1/document/extractions with {"documentType": "PASSPORT"} returns:

{
  "extractionHandle": "ex_0f3c9a1b7d2e4f60a8b9c0d1e2f3a4b5",
  "evidenceToken": "…",
  "evidenceTokenExpiresAt": "2026-10-10T09:15:00Z",
  "requiredEvidence": ["DATA_PAGE"],
  "acceptedEvidence": ["DATA_PAGE"],
  "uploadKeyThumbprints": ["…"],
  "environment": "LIVE"
}

The evidenceToken is returned once and never again. It is a bearer secret for this one capture: hand it only to the device that uploads and keep it for the fields fetch. Never log it and never put it in a URL. The capture expires 15 minutes after Start. requiredEvidence lists the parts that must be uploaded before the fields can be fetched; acceptedEvidence lists every part the upload admits — the required parts plus any optional one. A part outside the accepted set is refused (422); a fetch before every required part is uploaded is 409 EVIDENCE_INCOMPLETE.

2. Upload each part, encrypted on the device

The device photographs each part in requiredEvidence, encrypts it to Emnet’s upload key and uploads the ciphertext with your publishable key. Upload each part once; a retake is a new capture. A kebele card’s BACK is optional: it is in acceptedEvidence but not in requiredEvidence, so it may be uploaded and is not needed to fetch the fields. If an upload answers 503 the part was not stored — retry it. Nothing is extracted at upload: the part is only checked and stored, encrypted, until your backend fetches the fields. Use the document-capture package for this step; the envelope it builds is specified below.

3. Fetch the fields — once

When every part is uploaded, your backend calls POST /v1/document/extractions/{handle}/fields with the evidence token and a secret key. On a final answer (200, or 422 EVIDENCE_UNREADABLE) the token is consumed and the evidence and its keys are destroyed in the same call. A second fetch after a final answer answers 404: start a new capture (a retake). Emnet never stores extracted fields.

503 EXTRACTION_UNAVAILABLE is transient and retryable with the same token: the token is not consumed and the evidence is kept — this includes a response cut short by the server’s time budget for the call. Each such attempt counts toward a bounded number of extraction attempts; once the bound is spent the call answers 404 and a new capture is needed. Retry with back-off before the token expires. A 503 is an answer; a 504 or no answer is not.

{
  "extractionHandle": "ex_0f3c9a1b7d2e4f60a8b9c0d1e2f3a4b5",
  "documentType": "PASSPORT",
  "extractionMethod": "MRZ",
  "environment": "LIVE",
  "fields": {
    "surname":   { "value": "TESFAYE", "confidence": 0.95 },
    "given_names": { "value": "SELAM", "confidence": 0.95 },
    "birthdate": { "value": "1994-03-12", "confidence": 0.95 },
    "document_expiry": { "value": "2031-05-30", "confidence": 0.95 },
    "place_of_birth": { "value": "ADDIS ABABA", "confidence": 0.6 }
  },
  "missing": ["document_issue_date"]
}

Fields

Which fields you receive is set per document type by your account’s field policy (default: none). fields holds only the fields that were read and are allowed; missing lists the allowed fields that could not be read. No other key ever appears.

• Confidence. About 0.95 for a structured read (a barcode, or a machine-readable zone whose check digits passed without correction); about 0.6 for text read from the printed face. Flag any field below 0.80 for review.
• repaired is present, and true, only when the value passed its check digit after a single-character correction of a likely misread. It is evidence about extraction, never a verdict.
• The document number. For FAYDA_DIGITAL_ID only document_number_last4 is ever returned. For the other types the full document_number is returned only when your field policy lists it.
• extractionMethod — OCR, MRZ, BARCODE or QR — says how the fields were read, never whether the document is authentic. environment says which key environment produced the result; it does not make it a verification.

The evidence envelope

The uploaded file is never an image. It is a JWE (RFC 7516) in compact serialization, content type application/jose, whose plaintext is the JPEG or PNG image. The document-capture package builds it for you; this is the binding specification.

• alg exactly ECDH-ES+A256KW on curve P-256, enc exactly A256GCM, with a fresh ephemeral key pair for every part (epk: exactly kty, crv, x, y).
• A fresh content-encryption key and a fresh 96-bit IV for every part, from a cryptographically secure random generator — never reused across parts or captures.
• kid is the published name of the Emnet upload key the part is encrypted to; the RFC 7638 thumbprint is the trust anchor you pin. The only other header parameters allowed are typ and cty; a part carrying zip, crit, jku, x5u, jwk, x5c, x5t, x5t#S256, apu, apv or any other parameter, or any other alg or enc, is refused.
• Plaintext: JPEG or PNG only (detected by content, not by name), 200–6000 px per side, at most 25 megapixels and 8 MiB (8,388,608 bytes). HEIC/HEIF is refused — export JPEG on the device. The compact serialization is at most 11,534,336 bytes.

Request rules

• No query string on any document data-capture operation: a request with one is refused (400, or 404) — the token travels only in the body. Malformed paths are refused (400).
• A Content-Length header is required and chunked bodies are refused (411). Bodies are bounded (413). These refusals may arrive with an empty body.
• Every ownership mismatch — unknown handle, wrong or expired token, another account’s or another environment’s capture, a capture already fetched, an unregistered origin — is the same 404 NOT_FOUND. It never reveals which.

Errors

{
  "success": false,
  "error": { "code": "EVIDENCE_UNREADABLE", "message": "evidence could not be read — retake", "retakeHint": "GLARE" }
}

retakeHint is one of BLUR, DARK, GLARE, NO_TEXT, BARCODE_UNREADABLE or UNSUPPORTED_DOCUMENT. It describes image quality only, never authenticity — use it to ask for a better photo.

Next

• Document-capture package — install and use it in a browser or a React Native app.
• Java SDK — startDocumentExtraction and fetchExtractionFields on your backend.
• API reference — the three operations.