Skip to main content

POST /Document/extraction

Extracts structured fields from a single document, using the templates configured for your tenant. The platform automatically picks the best template for the uploaded document; you can also bias the prompt by sending a ComplementaryPrompt to nudge the model toward extra fields or specific phrasing.

📷 Paste here: screenshot of the Template editor on the platform, so the reader understands where the schemas being extracted come from.

Endpoint​

POST https://api-eu.cogneris.ai/Document/extraction

Authentication​

Send your API key as a Bearer token. See Getting Started for how to generate one.

Authorization: Bearer xtkt_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxx

Request​

Content-Type: multipart/form-data

FieldTypeRequiredDescription
filefile✅The document to extract from.
ComplementaryPromptstring❌Free-text instruction appended to the model prompt. Use it to ask for extra fields, enforce formatting, or narrow the scope.

Constraints

  • Allowed extensions: .pdf, .png, .jpg, .jpeg, .tiff, .tif, .bmp, .doc, .docx.
  • Max size: 10 MB.
  • Rate limit: 50 requests/minute per API key.

Response​

200 OK — the envelope's data carries a unique extraction id, the templateId that was applied, and a metadata payload with one key per field of the template, directly under metadata. Each field is an object with the extracted value, its confidence (0–100) and, when the value was located on the page, page, bbox ([x0, y0, x1, y1] page fractions, origin top-left) and bbox_confidence (0–100). Those three location keys are present or absent together. A list field (line items, statement movements) is an array of rows whose cells have the same shape:

{
  "data": {
    "id": "9d8a7c6e-1b2f-4a3d-9e8f-7c6d5b4a3210",
    "templateId": "3f2b1c0d-4e5f-4a6b-8c7d-9e0f1a2b3c4d",
    "metadata": {
      "supplier": { "value": "Acme Industries", "confidence": 97, "page": 1, "bbox": [0.08, 0.06, 0.41, 0.09], "bbox_confidence": 93 },
      "invoiceNumber": { "value": "INV-2026-00123", "confidence": 98, "page": 1, "bbox": [0.62, 0.11, 0.83, 0.14], "bbox_confidence": 92 },
      "issueDate": { "value": "2026-05-12", "confidence": 96, "page": 1, "bbox": [0.62, 0.15, 0.80, 0.18], "bbox_confidence": 90 },
      "total": { "value": "1542.30", "confidence": 95 },
      "lineItems": [
        {
          "description": { "value": "Widget A", "confidence": 97, "page": 1, "bbox": [0.08, 0.41, 0.35, 0.44], "bbox_confidence": 90 },
          "amount": { "value": "1000.00", "confidence": 96, "page": 1, "bbox": [0.78, 0.41, 0.91, 0.44], "bbox_confidence": 89 }
        },
        {
          "description": { "value": "Service fee", "confidence": 95, "page": 1, "bbox": [0.08, 0.45, 0.35, 0.48], "bbox_confidence": 88 },
          "amount": { "value": "542.30", "confidence": 96, "page": 1, "bbox": [0.78, 0.45, 0.91, 0.48], "bbox_confidence": 89 }
        }
      ]
    },
    "createdDate": "2026-05-19T13:42:11Z"
  },
  "meta": { "httpStatusCode": 200, "messages": [] },
  "hasErrors": false
}

There is no metadata.fields wrapper: read a value as data.metadata.<field>.value (for example data.metadata.invoiceNumber.value). A value the model could not locate on the page — a computed total, for instance — comes without page, bbox and bbox_confidence; that is not an error. The field keys depend entirely on the template that matched. Templates are managed in the platform — change the schema there and this endpoint returns the new keys on the next call.

Example — curl​

curl -X POST "https://api-eu.cogneris.ai/Document/extraction" \
  -H "Authorization: Bearer xtkt_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
  -F "file=@./invoice.pdf" \
  -F "ComplementaryPrompt=Also extract the buyer's tax id if present."

Example — Python​

import requests

API_KEY = "xtkt_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxx"
BASE_URL = "https://api-eu.cogneris.ai"

with open("invoice.pdf", "rb") as fp:
    response = requests.post(
        f"{BASE_URL}/Document/extraction",
        headers={"Authorization": f"Bearer {API_KEY}"},
        files={"file": ("invoice.pdf", fp, "application/pdf")},
        data={"ComplementaryPrompt": "Also extract the buyer's tax id if present."},
    )

response.raise_for_status()
print(response.json()["data"]["metadata"])

Example — Node.js​

import fs from "node:fs";

const API_KEY = "xtkt_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxx";
const BASE_URL = "https://api-eu.cogneris.ai";

const form = new FormData();
form.append("file", new Blob([fs.readFileSync("./invoice.pdf")]), "invoice.pdf");
form.append("ComplementaryPrompt", "Also extract the buyer's tax id if present.");

const response = await fetch(`${BASE_URL}/Document/extraction`, {
  method: "POST",
  headers: { Authorization: `Bearer ${API_KEY}` },
  body: form,
});

const { data } = await response.json();
console.log(data.metadata);

Errors​

HTTP statusReason
400 Bad RequestMissing file, empty file, disallowed extension, or file over 10 MB.
401 UnauthorizedMissing/invalid/revoked API key.
403 ForbiddenTenant has no active subscription for extraction.
422 Unprocessable EntityNo template matched the document — set up a matching template in the platform before retrying.
429 Too Many RequestsAPI key exceeded the 50 req/min limit.