Documents

A Document is a single processed page — an uploaded image, or one page rendered out of an uploaded PDF. Every Document belongs to a Batch (identified by batch_name), which is the unit you actually start processing on. Uploading a multi-page PDF creates one Document per page in the same batch — see Upload a document below.

Upload a document

Uploads a single file (image or PDF) into a batch. If batch_name is omitted, one is auto-generated and returned in the response. Uploading does not start extraction — call Start processing a batch once you've uploaded everything you want processed together. The response's remaining_batch_capacity tells you how many more documents this batch can accept before hitting your plan's max batch size (see Account's max_batch_size) — useful for deciding client-side whether to keep adding to this batch or start a new one, without a separate lookup.

POST /api/v1/documents

Parameters

Name	Location	Type	Description
`file`	body (multipart)	file	Required unless `url` is given. An image (JPEG/PNG/etc.) or a PDF. PDFs are capped at 30 pages per upload and are split one Document per page.
`url`	body (multipart)	string, optional	Alternative to `file` — the server downloads the file from this URL instead of you needing to attach it. Mutually exclusive with `file`; pass exactly one. Must be a public `http://` or `https://` URL (no localhost/private-network addresses); the download is capped at 30MB with a 15-second read timeout.
`batch_name`	body (multipart)	string, optional	Batch to add this document to. Omit to auto-generate a new batch name (returned in the response). Reuse the same value across multiple uploads to build up one batch before processing it.
`template_id`	body (multipart)	integer, optional	A Template ID owned by your account to pre-associate with this document. Not required — you can also pass a template (or ad-hoc fields) when you call `process`.
`password`	body (multipart)	string, optional	PDF-only. Tried first if the file is password-protected. If omitted, or if it doesn't unlock the file, falls back to any passwords already saved under your account's Email Inbox settings — this field doesn't require you to have Email Inbox set up at all, it's just a per-call alternative to it.
`Idempotency-Key`	header, optional	string	Safe to retry. See Idempotency.

PDF uploads return an array, not a single ID. Uploading a PDF renders every page as its own Document and the response's document_id becomes a JSON array (one string per page, in page order), plus a page_count field. A single image upload returns a scalar string instead. Client code that assumes document_id is always a string will break on a PDF upload — check whether the file you're sending is a PDF and branch on the response shape, or always send images and never rely on the scalar case. See the two response examples on the right.

Possible errors

missing_api_key / invalid_api_key / plan_required — see Error Handling.
missing_parameter — neither file nor url was sent.
invalid_parameter (param: "file") — invalid/corrupted image or PDF, a password-protected PDF that couldn't be unlocked (neither the password field nor any saved Email Inbox password worked), or a PDF over the 30-page limit.
invalid_parameter (param: "url") — both file and url were sent, the URL doesn't resolve to a public address, the download failed or timed out, or the downloaded file exceeds 30MB.
invalid_parameter (param: "batch_name") — the batch is already at your plan's max batch size.
invalid_parameter (param: "template_id") or template_not_found.
rate_limit_exceeded — too many unprocessed (queued) documents on the account already; process or delete some first.

Get a document

Fetch a single document's current status and, once extraction has succeeded, its reshaped line_items. This is the single-document equivalent of Get batch results — same reshape rules, but without the ?include=bbox option (that's only on the batch-level results endpoint).

GET /api/v1/documents/{document_id}

Parameters

Name	Location	Type	Description
`document_id`	path	string	The document ID returned by `POST /documents` (or one entry of that array, for a PDF page).

status is always one of queued, processing, succeeded, failed, canceled — see the Async Model guide for the state machine. completed_at is set once the document reaches a terminal state (succeeded, failed, or canceled) and stays null before that.

Possible errors

missing_api_key / invalid_api_key / plan_required — see Error Handling.
document_not_found — no document with this ID on your account.

Get a document's image

Returns the page image behind a document — the full page by default, or a normalized crop of it with ?crop=. This is what powers image_url on pure-location fields (see Get batch results), but you can also call it directly with your own coordinates.

GET /api/v1/documents/{document_id}/image

Parameters

Name	Location	Type	Description
`document_id`	path	string	The document ID.
`crop`	query, optional	string	`"x1,y1,x2,y2"` — four floats between 0 and 1, same normalized coordinate convention as every `bbox` object elsewhere in the API. Omit to get the full, uncropped page image.

The response is the raw image bytes (Content-Type: image/jpeg), not JSON — there's no response JSON example on the right for this endpoint, just the request.

Possible errors

missing_api_key / invalid_api_key / plan_required — see Error Handling.
document_not_found — no document with this ID, or the original image file is no longer available (e.g. it's past your account's auto-delete retention window).
invalid_parameter (param: "crop") — malformed crop value, coordinates outside 0–1, or a crop region that's empty after clamping to the image bounds.

Trigger bbox annotation

Explicitly starts the optional, paid, second-pass job that locates where each extracted field's value physically sits on the page. This is a separate billable action from extraction itself — see the Bounding Boxes guide before wiring this in, especially the note about your account's auto_annotate_bbox setting possibly triggering (and billing) this same job automatically without you ever calling this endpoint.

POST /api/v1/documents/{document_id}/bbox

Parameters

Name	Location	Type	Description
`document_id`	path	string	Must already be a `succeeded` document with extracted data — you can't annotate a document that hasn't finished extraction yet.
`Idempotency-Key`	header, optional	string	Recommended — this action spends credits. See Idempotency.

Returns 202 when a new bbox job was just enqueued, or 200 when a bbox job for this document was already running (already_running: true) — meaning you already called this same endpoint for this document once before and that earlier bbox job hasn't finished yet. This is unrelated to whether the document's own extraction has finished — bbox can only be triggered on a document that's already succeeded (see "Possible errors" below), so by the time you can call this endpoint at all, extraction is done. already_running is purely about a second bbox job for the same document, not about the extraction job. Either way (202 or 200), nothing new is started or charged on the 200 path — poll Get bbox annotation with the returned group_batch_id for the result.

Possible errors

missing_api_key / invalid_api_key / plan_required — see Error Handling.
document_not_found — no document with this ID on your account.
insufficient_credits — not enough credits to run this annotation pass.
invalid_parameter — the document isn't in a valid state for this yet (still processing), or has no extracted data to locate boxes for.

Get bbox annotation

Polls the status of, and fetches results from, the most recent bbox-annotation job triggered for a document. If no job has ever been triggered for this document, exists is false and status/group_batch_id are null — this is a normal, common response (most documents never have bbox triggered at all), not an error.

GET /api/v1/documents/{document_id}/bbox

Parameters

Name	Location	Type	Description
`document_id`	path	string	The document ID.

rows maps a row index (as a string, e.g. "0") to a map of field name → normalized bbox object (or null if that field's location wasn't found on the page). status uses the same closed 5-value enum as everywhere else in the API.

Possible errors

missing_api_key / invalid_api_key / plan_required — see Error Handling.
document_not_found — no document with this ID on your account.

import os import uuid import requests response = requests.post( "https://imagetotable.ai/api/v1/documents", headers={ "Authorization": f"Bearer {os.environ['API_KEY']}", "Idempotency-Key": str(uuid.uuid4()), }, files={"file": open("invoice.jpg", "rb")}, data={"batch_name": "july-invoices"}, ) print(response.json())

import { readFile } from "node:fs/promises"; const formData = new FormData(); formData.append("file", new Blob([await readFile("invoice.jpg")]), "invoice.jpg"); formData.append("batch_name", "july-invoices"); const response = await fetch("https://imagetotable.ai/api/v1/documents", { method: "POST", headers: { "Authorization": `Bearer ${process.env.API_KEY}`, "Idempotency-Key": crypto.randomUUID(), }, body: formData, }); console.log(await response.json());

curl -X POST https://imagetotable.ai/api/v1/documents \ -H "Authorization: Bearer $API_KEY" \ -H "Idempotency-Key: $(uuidgen)" \ -F "url=https://imagetotable.ai/static/samples/invoice.webp" \ -F "batch_name=july-invoices"

import os import uuid import requests response = requests.post( "https://imagetotable.ai/api/v1/documents", headers={ "Authorization": f"Bearer {os.environ['API_KEY']}", "Idempotency-Key": str(uuid.uuid4()), }, data={ "url": "https://imagetotable.ai/static/samples/invoice.webp", "batch_name": "july-invoices", }, ) print(response.json())

{ "document_id": [ "8f14e45f-ceea-467e-9de1-a3e9c93a9c95_p1", "8f14e45f-ceea-467e-9de1-a3e9c93a9c95_p2" ], "batch_name": "july-invoices", "page_count": 2, "remaining_batch_capacity": 198 }

import os import requests response = requests.get( "https://imagetotable.ai/api/v1/documents/8f14e45f-ceea-467e-9de1-a3e9c93a9c95", headers={"Authorization": f"Bearer {os.environ['API_KEY']}"}, ) print(response.json())

const response = await fetch("https://imagetotable.ai/api/v1/documents/8f14e45f-ceea-467e-9de1-a3e9c93a9c95", { headers: { "Authorization": `Bearer ${process.env.API_KEY}` }, }); console.log(await response.json());

{ "document_id": "8f14e45f-ceea-467e-9de1-a3e9c93a9c95", "batch_name": "july-invoices", "filename": "invoice_042.jpg", "status": "succeeded", "created_at": "2026-07-16T09:12:03+00:00", "started_at": "2026-07-16T09:12:05+00:00", "completed_at": "2026-07-16T09:12:14+00:00", "line_items": [ { "invoice_number": "INV-1042", "invoice_date": "2026-07-01", "total_amount": "1,204.50" } ] }

import os import requests response = requests.get( "https://imagetotable.ai/api/v1/documents/8f14e45f-ceea-467e-9de1-a3e9c93a9c95/image", headers={"Authorization": f"Bearer {os.environ['API_KEY']}"}, ) with open("page.jpg", "wb") as f: f.write(response.content)

import { writeFile } from "node:fs/promises"; const response = await fetch("https://imagetotable.ai/api/v1/documents/8f14e45f-ceea-467e-9de1-a3e9c93a9c95/image", { headers: { "Authorization": `Bearer ${process.env.API_KEY}` }, }); await writeFile("page.jpg", Buffer.from(await response.arrayBuffer()));

import os import requests response = requests.get( "https://imagetotable.ai/api/v1/documents/8f14e45f-ceea-467e-9de1-a3e9c93a9c95/image", headers={"Authorization": f"Bearer {os.environ['API_KEY']}"}, params={"crop": "0.10,0.08,0.42,0.30"}, ) with open("crop.jpg", "wb") as f: f.write(response.content)

import { writeFile } from "node:fs/promises"; const url = new URL("https://imagetotable.ai/api/v1/documents/8f14e45f-ceea-467e-9de1-a3e9c93a9c95/image"); url.searchParams.set("crop", "0.10,0.08,0.42,0.30"); const response = await fetch(url, { headers: { "Authorization": `Bearer ${process.env.API_KEY}` }, }); await writeFile("crop.jpg", Buffer.from(await response.arrayBuffer()));

import os import uuid import requests response = requests.post( "https://imagetotable.ai/api/v1/documents/8f14e45f-ceea-467e-9de1-a3e9c93a9c95/bbox", headers={ "Authorization": f"Bearer {os.environ['API_KEY']}", "Idempotency-Key": str(uuid.uuid4()), }, ) print(response.json())

const response = await fetch("https://imagetotable.ai/api/v1/documents/8f14e45f-ceea-467e-9de1-a3e9c93a9c95/bbox", { method: "POST", headers: { "Authorization": `Bearer ${process.env.API_KEY}`, "Idempotency-Key": crypto.randomUUID(), }, }); console.log(await response.json());

import os import requests response = requests.get( "https://imagetotable.ai/api/v1/documents/8f14e45f-ceea-467e-9de1-a3e9c93a9c95/bbox", headers={"Authorization": f"Bearer {os.environ['API_KEY']}"}, ) print(response.json())

const response = await fetch("https://imagetotable.ai/api/v1/documents/8f14e45f-ceea-467e-9de1-a3e9c93a9c95/bbox", { headers: { "Authorization": `Bearer ${process.env.API_KEY}` }, }); console.log(await response.json());

{ "document_id": "8f14e45f-ceea-467e-9de1-a3e9c93a9c95", "exists": true, "status": "succeeded", "group_batch_id": "bx_8a3c2e1f", "rows": { "0": { "invoice_number": {"x1": 0.121, "y1": 0.084, "x2": 0.418, "y2": 0.112, "unit": "normalized"}, "total_amount": null } } }