---
title: "Submit the extraction of values from a document (async, vision model, structured output)"
method: POST
path: "/extractions"
---

# Submit the extraction of values from a document (async, vision model, structured output)

`POST /extractions`

## Request

- Base URL: `/api/v1` (relative, and the document was published on a file host, not at the API’s origin)
- URL: `/api/v1/extractions`
- Auth: none declared. Required headers: `Idempotency-Key`
- TypeScript: <https://skmtc.dev/cdc/apis/zia-translation-service/docs/extractions/post.ts> (a function with typed inputs; its response is checked against the schema)

Generic extraction of values from a document (PDF or image), e.g. used by `ole-sumex-invoice-parser` with the `sumex-invoice` profile when classic extraction is incomplete. Each page is analysed by the internal vision model, whose answer is constrained by a JSON Schema generated by the service from the requested keys (`context.missingFields`) and their definition in the profile (see `/extraction-profiles`). Without profile, every key is extracted as free text. Values are normalized (dates `yyyy-MM-dd`, amounts/numbers with `.`, identifiers without separators) and the confidence of the model is capped when no `evidence` is given or when the value is not found in its evidence. The value with the highest confidence is kept for each key. When the profile classifies its pages (e.g. `sumex-invoice`) or when `context.pageHints` is given, the pages are first classified (`MAIN`: the one invoice of the file; `SUPPORTING`: supporting documents; `OTHER`: blank or unreadable pages): pages with a hint are not classified again, the other pages are classified one by one by the vision model. The values are then extracted from the pages of the main document only, sent together (at most `zia.extraction.max-images-per-call` images per call), unclassified pages being treated as pages of the main document; without main document, all the pages except `OTHER` ones are analysed. The classification of the pages is returned in `result.pages`. Idempotent on `Idempotency-Key`: a known key returns the existing job. Jobs are kept `zia.extraction.job-ttl` (default 24h) after their completion.

## Headers

- `Idempotency-Key` string, required

## Request body `multipart/form-data`

- object
  - `file` string, binary, required: The document (PDF, PNG, JPEG, GIF or BMP)
  - `context` ExtractionContext, required
    - `profile` string: Id of a server-side extraction profile (e.g. `sumex-invoice`); ad hoc extraction when absent
    - `documentId` string
    - `language` string: Expected language of the document (hint for the model)
    - `knownFields` object: Values already known (key = field key), given to the model as hints
    - `missingFields` string[], required: Keys to extract. With a profile: keys of its fields and collections (e.g. `biller.gln`, `services`), unknown keys being ignored with a warning. Without profile: free keys matching `[A-Za-z0-9_][A-Za-z0-9_.-]{0,99}`, extracted as text.
    - `instructions` string: Additional instructions for the model
    - `pageHints` PageClassification[]: Classification of pages already known by the client (e.g. from the text layer), kept as given: these pages are not classified again. Pages without hint are classified by the vision model. `confidence` and `evidence` are not expected.
      - `page` integer, required: 1-based page of the file
      - `documentRole` 'MAIN' | 'SUPPORTING' | 'OTHER', required: `MAIN`: page of the invoice addressed to the insurance or to the insured person (source of the values); `SUPPORTING`: supporting document (e.g. invoice of a manufacturer addressed to the provider); `OTHER`: blank page, separator, unreadable page.
      - `documentType` 'FORM' | 'INVOICE' | 'CREDIT_NOTE' | 'REMINDER' | 'QUOTE' | 'PRESCRIPTION' | 'REPORT' | 'COVER_LETTER' | 'POWER_OF_ATTORNEY' | 'OTHER': Generic type of the document the page belongs to
      - `formId` string: Identifier printed on a form (e.g. `300.001`), when the page belongs to a form
      - `confidence` number, double
      - `evidence` string: Text that justifies the classification (title, recipient...)

## Response `202`

Job created (or existing job for this `Idempotency-Key`)

- ExtractionJob
  - `jobId` string, required
  - `status` 'PENDING' | 'RUNNING' | 'SUCCEEDED' | 'FAILED', required
  - `submittedAt` string, date-time
  - `result` ExtractionResponse
    - `profile` string
    - `documentType` string: Free classification of the document (informative)
    - `pages` PageClassification[]: Classification of each page of the file, present when the pages are classified (unclassified pages are absent). The fields and collection rows then come from the `MAIN` pages only.
      - `page` integer, required: 1-based page of the file
      - `documentRole` 'MAIN' | 'SUPPORTING' | 'OTHER', required: `MAIN`: page of the invoice addressed to the insurance or to the insured person (source of the values); `SUPPORTING`: supporting document (e.g. invoice of a manufacturer addressed to the provider); `OTHER`: blank page, separator, unreadable page.
      - `documentType` 'FORM' | 'INVOICE' | 'CREDIT_NOTE' | 'REMINDER' | 'QUOTE' | 'PRESCRIPTION' | 'REPORT' | 'COVER_LETTER' | 'POWER_OF_ATTORNEY' | 'OTHER': Generic type of the document the page belongs to
      - `formId` string: Identifier printed on a form (e.g. `300.001`), when the page belongs to a form
      - `confidence` number, double
      - `evidence` string: Text that justifies the classification (title, recipient...)
    - `fields` object: Values found, by key; a key that was not found is absent
    - `collections` object: Rows of each requested collection (row = values by field name)
    - `warnings` string[]
  - `error` object
    - `code` 'UNREADABLE_DOCUMENT' | 'EXTRACTION_FAILED' | 'INTERNAL_ERROR'
    - `message` string

## Other responses

- `400`: Missing/invalid `Idempotency-Key`, `file` or `context`, unsupported document type, unknown profile, no extractable key, too many keys (`zia.extraction.max-fields`) or instructions too long
- `413`: Document too large
- `429`: Too many extractions in progress (retry later)

## Changes

- **2026-10-23** `17816f6177b4`: 2 info
  - added the new optional request property `context/pageHints`
  - added the optional property `result/pages` to the response with the `202` status
- **2026-10-23** `db02012fc3ba`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/cdc/apis/zia-translation-service/changes/extractions/post.md)

---

[API](https://skmtc.dev/cdc/apis/zia-translation-service.md) - [All operations](https://skmtc.dev/cdc/apis/zia-translation-service/llms.txt) - [OpenAPI document](https://skmtc.dev/cdc/apis/zia-translation-service/revisions/17816f6177b4?raw)