Document data extraction API: documents in, clean JSON out

Most teams that go looking for a document extraction API want the same thing: a file goes in from a mailbox, a portal or another system, and structured data comes out in a form their code can trust. The hard parts are rarely the HTTP calls. They are teaching the service your documents, knowing when a value is unsure, and handling the day your endpoint is down.

This guide walks through all of it using Paige, Ademero's cloud document AI, with real field names from its API. Where a desktop tool would serve you better, it says so.

The shape of the job

Paige organizes work into jobs. A job is one stream of documents, such as your accounts payable mail or your freight paperwork. Each job has its own setup (document types, fields, tables, file naming), its own email address, and its own destinations. Everything below happens per job.

Getting documents in

Paige takes documents four ways, and you can mix them within one job:

Sending files through the API

A batch is one upload of one or more files. Paige splits the files into pages and documents and reads them. Files can be PDF, TIFF, PNG or JPEG, up to 10 MB each and about 28 MB per request; send larger sets as several batches. Every call that creates something carries an Idempotency-Key of your own, so a retry after a timeout never creates the batch twice.

curl <paige>/v1/batches \
  -H "Authorization: Bearer $PAIGE_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -F "job=<job id>" \
  -F "files=@bowman-4801.pdf" -F "files=@march-statements.tif"

201 Created
{"id": "<batch id>", "state": "processing", "pageCount": 4, "documentIds": [], ...}

A file Paige cannot read costs that file and nothing else: the rest of the batch goes in, and the skipped file is named with the reason. The API reference, quickstart programs in curl, Python, C# and JavaScript, and an OpenAPI document for generating a typed client are in the app under Developers.

Teaching a job from samples

There are no templates to draw. You open the job in the Paige web app and give it real documents: a folder of last month's invoices, a stack of bills of lading. Paige reads them and proposes the document types it found, the fields for each type and any tables. You confirm or correct the proposal, and the job reads that way from then on, whichever way documents arrive.

• Use real, varied samples. Your biggest senders, a few one-offs, a faint scan and a long multi-page document teach more than twenty copies of one clean layout.
• Name fields for your system. The field names you settle on are the names in the JSON, so pick the ones your integration expects.
• Corrections teach. When a person fixes a value in review, the job learns from it. A document corrected after it was delivered goes out again as a new revision.

What comes back

One upload can hold many documents. A batch's documentIds lists the documents Paige split it into, and each document has:

• A type, from the job's setup (invoice, bill_of_lading and so on).
• Its pages, each with the file and page number it came from, so you can trace a document back to the upload.
• Fields, each with its name, its value as text, a confidence from 0 to 1, and where it was read: the page_id and an evidence box in fractions of the page from its top-left corner. Use the box to highlight the value on the page in your own review screen.
• Line items, the table rows in the document's own order: row, description, quantity, unit_price, amount, confidence and page_number. The list is always there, empty when a document has no table.
• Where it was filed: the folders and file name the job's file naming gave it, used by every destination.
• A revision number. A document corrected later is delivered again with a higher revision. Upsert on the document id and keep the highest revision.

Here is what a webhook receives for the sample Bowman Fabrication invoice from our screenshots. It is an example: simplified, with ids shortened and two line items and some fields left out. The document inside is the same document.json you can download.

POST /paige/webhook HTTP/1.1
Content-Type: application/json
Paige-Event: document.confirmed
Paige-Delivery: 8b0f3a526c1e4f7a9d2b0e4c5a6b7c8d
Paige-Signature: t=1791076374,v1=6ac8372bd58e...

{
  "event": "document.confirmed",
  "delivery_id": "8b0f3a52-6c1e-4f7a-9d2b-0e4c5a6b7c8d",
  "attempt": 1,
  "job_id": "9e447cc1-...",
  "document": {
    "id": "a185de74-...",
    "revision": 1,
    "type": "invoice",
    "pages": [
      {"id": "bc899827-...", "source_file": "bowman-4801.pdf", "page_number": 1}
    ],
    "fields": [
      {"name": "vendor_name", "value": "Bowman Fabrication, LLC", "confidence": 0.99,
       "page_id": "bc899827-...",
       "evidence": {"x": 0.08, "y": 0.04, "width": 0.29, "height": 0.02}},
      {"name": "document_number", "value": "4801", "confidence": 0.99, ...},
      {"name": "document_date", "value": "March 9, 2026", "confidence": 0.98, ...},
      {"name": "total_amount", "value": "$5,910.00", "confidence": 0.97, ...}
    ],
    "line_items": [
      {"row": 1, "description": "CNC-machined steel bracket, A36", "quantity": 240,
       "unit_price": 18.5, "amount": 4440, "confidence": 0.98, "page_number": 1},
      {"row": 2, "description": "Powder-coat finish, RAL 7016", "quantity": 240,
       "unit_price": 3.25, "amount": 780, "confidence": 0.98, "page_number": 1}
    ],
    "filed": {"folders": ["invoice", "2026-03"],
              "name": "Bowman Fabrication_4801_2026-03-09", "notes": []},
    "exported_at": "2026-10-03T14:02:11Z"
  },
  "package": {
    "json": "<paige>/v1/documents/a185de74-.../package/document.json",
    "pdf": "<paige>/v1/documents/a185de74-.../package/pages.pdf"
  }
}

Two details save debugging time. Keys inside a document are snake_case (unit_price, page_id) while the rest of the API is camelCase. And field values are text, so a date can arrive as it was printed; parse and validate on your side.

Download, SFTP or webhook

When a document is confirmed, Paige writes its package: document.json and pages.pdf, a searchable PDF/A-2 with every field also stored in the PDF's own metadata. Then it delivers to each of the job's destinations.

A destination added later can be sent what it missed. For SFTP, Paige pins your server's host key on the first connection and refuses any other key after that, and its Test button lists what it sees in the folder. Passwords, private keys and webhook secrets are write-only: once saved, the API never shows them again.

Webhook security and retries

A webhook is a job destination with an https address on the public internet and a secret of your own of at least 16 characters. The Test button sends a signed test event and shows what your endpoint answered. Every real delivery carries three headers: Paige-Event, Paige-Delivery and Paige-Signature.

Check the signature

Paige-Signature is t=<unix seconds>,v1=<hex>, where v1 is HMAC-SHA256 keyed with your secret over t, a full stop and the raw body. Check it over the bytes exactly as they arrived, before parsing, compare in constant time, refuse a timestamp more than five minutes off, and answer 401 to a post that fails.

// Node.js: check Paige-Signature before you trust or parse the body
import crypto from 'node:crypto';

function verify(rawBody, header, secret) {
  const parts = Object.fromEntries(header.split(',').map(p => p.split('=')));
  const t = Number(parts.t);
  if (!t || Math.abs(Date.now() / 1000 - t) > 300) return false; // 5 minutes
  const expected = crypto.createHmac('sha256', secret)
    .update(`${t}.${rawBody}`).digest('hex');
  const a = Buffer.from(expected), b = Buffer.from(parts.v1 ?? '');
  return a.length === b.length && crypto.timingSafeEqual(a, b);
}

How deliveries behave

• At least once. A post can arrive twice. Paige-Delivery is the same on every attempt of one revision to one webhook, so keep the ids you have handled and answer 200 to one you have already seen.
• Answer quickly. Any 2xx counts as received, and Paige waits up to 30 seconds. Store the post, answer, then do the slow work.
• Retries. Any other answer, or none, is tried again with growing waits (2, 4, 8 seconds and up), five attempts in all. Then the delivery has failed and the destination shows as down with what your endpoint said. A 401 or 403 is read as your endpoint refusing the signature. Fix it and press Retry to send everything that failed.
• Order. Posts are not ordered across documents. For one document, a later revision has a higher number.

Error handling

Every API error is a problem document with a code your code can switch on and a requestId to quote to support. The ones you are most likely to meet:

Beyond HTTP errors, watch the states:

• A batch settles as complete (everything exported), review (the rest exported, some documents waiting for a person) or needs_attention.
• A document in exception has stopped, for example an unreadable file or a destination that refused it. Its reason says why, and the job's exceptions list collects them in one place.
• Each destination shows its health (healthy, degraded while retrying, down) and the last error, on the job page and in the API.

What waits for a person

Every reading ends in a check. A document that passes is exported at once. A document Paige is unsure of (a missing value, a low confidence, an uncertain type) is finished according to the job's processing mode:

A document on which nothing at all was read is held for a person in every mode, so it never reaches your system empty. For an API integration this means review happens in Paige; your webhook only ever receives confirmed revisions.

Click to enlarge

When a desktop tool is the better fit

An API is the right shape when documents already exist as files in other systems and the data has to flow on without anyone touching it. It is the wrong shape for a scanning desk with paper in hand, or when documents may not leave the building.

Go-live checklist

• Set the job up from real samples

  Confirm the types, field names and tables your integration expects.

• Keep the API key and webhook secret in a secret store

  Name the key for the system that uses it, so it can be revoked alone.

• Send an Idempotency-Key with every change

  Reuse it on retries; a new one per new batch.

• Verify every webhook signature over the raw body

• De-duplicate on Paige-Delivery and upsert on revision

• Answer fast, work later

  Return a 2xx as soon as the post is stored.

• Parse and validate values yourself

  Dates and amounts arrive as text.

• Start on Human review

  Move to an automatic mode once the job has proved itself.

• Alert on a destination going down

• Set how long Paige keeps documents

  7 days, 30 days, a year or forever after export; download what you must keep.

Questions