An API for extracting data from invoices

Pulling structured data off an invoice — vendor, invoice number, date, line totals, tax — is one of the most common document-automation jobs there is, and one of the most tedious to build by hand. Regex over OCR text breaks the moment a vendor changes their layout. Template-matching tools want you to draw boxes for every supplier. What you actually want is an API for extracting data from invoices that reads any layout, returns clean named fields, and — crucially — tells you where on the page each value came from so you can trust the result.

That last part is the whole game. An invoice extraction endpoint that hands back total: 2,045 with no provenance is a liability in an accounts-payable pipeline. This guide walks through space-ocr's POST /ocr/fields endpoint: a single synchronous call that takes one invoice image, applies the field schema you declare (or lets autoFields propose one), and returns every value with source coordinates and an explicit review verdict.

See the output before you write a line of code

Below is a real parsed receipt. Hover any field and the box on the image lights up — that box is exactly where the value was read from, and each value carries its own verification verdict and supporting evidence. Invoices behave the same way: every field you extract lands back on the pixels it came from.

Authentication and base URL

The public API lives at a single base — https://api.space-ocr.com — with no /v1 path versioning. Every request authenticates with an HTTP Bearer token whose key is prefixed spocr_:

Authorization: Bearer spocr_xxxxxxxxxxxxxxxx

A missing or invalid key returns 401 with error.code: "invalid_api_key". 403 means something else entirely: the key is valid, but the resource sits outside its scope — a job created by another key, for example. Every response carries an X-Request-Id header (format req_xxx) you should log for support traces. The full spec is published as OpenAPI 3.1 at GET /openapi.json if you'd rather generate a client.

The simplest call: an explicit invoice schema

The fastest path is to name the fields you want. fields takes an array of FieldSpec objects, and the response comes back shaped exactly like that declaration — no template to pick, no boxes to draw. imageType is required and says how image is carried: "url" or "base64".

Declaring a scalar type does more than document intent. invoice_date as "date" and the money fields as "number" add a deterministic data.normalized layer beside the raw reading. required: true on invoice_no means an empty or absent value comes back on the review list instead of passing quietly as an empty string. The pattern is your own numbering convention — matching is partial, as in JSON Schema, so anchor it with ^…$ to check the whole value.

If you don't know the schema yet, send autoFields: true with no fields at all and the model proposes one from the document itself. That is the right way to explore an unfamiliar supplier form; once the field names settle, move them into an explicit fields array so the response shape stops moving between calls.

The response shape

A successful call returns { status: "success", data: { ... } }. The data splits into four parts, and each has exactly one job:

• data.values — the business data, shaped exactly like the fields you declared. Nothing else lives here.
• data.cells — a flat map keyed by path (total, line_items[0].unit_price). Each cell carries a box { xmin, ymin, xmax, ymax } on a 0–1000 normalized grid (0,0 = top-left, 1000,1000 = bottom-right), a quad of four ordered points that follows the page's tilt so a skewed phone photo still boxes cleanly, and then verified, review and evidence. Convert to pixels against data.image: pixel_x = box.xmin / 1000 × data.image.width.
• data.review — the summary: unit: "field", the declared / returned / boxed / verified counts, flagged (an array of { path, reasons }) and a by_reason histogram. The number of items needing attention is flagged.length; there is no separate counter, and by_reason counts every reason rather than one per item, so its total can be larger.
• data.normalized — a sparse tree shaped like values, holding the deterministic parse of the fields you gave a scalar type or a pattern. values is never overwritten.

verified is a verdict, not a character score: false whenever the cell carries review reasons of any kind, true when a check ran and nothing was flagged, null when there was nothing to check — a row union, for instance. The character cross-check itself is evidence.text_match, which is why verified: false together with text_match: true is a normal combination: the glyphs agreed and a rule you declared caught the value anyway. evidence also carries source (vision_symbol_match, token_id and others), match_ratio, and printed_text — the glyphs the OCR pass read at those coordinates, which is what you compare against when you need an exact string match.

Reason codes are contract vocabulary and are never translated: text_mismatch, missing, pattern_mismatch, type_mismatch, out_of_range, low_ratio, overwide_box and the rest. reasons is always an array, ranked so index 0 is the primary one — map the codes you handle and fall back to a generic message for anything new.

Declarations that turn into review signals

Beyond naming a field, a FieldSpec can declare what a good value looks like — and each declaration has one review reason attached to it. required: true raises missing when the value comes back empty or not at all, which is the one failure the character cross-check can never see on its own. pattern raises pattern_mismatch, enum does the same when the value falls outside the set, min / max raise out_of_range against the normalized number, and a scalar type raises type_mismatch when the value won't parse.

None of this is shown to the model. Declarations do not make extraction more accurate — the value comes back the same either way. What they decide is which paths land in data.review.flagged and, in the case of label, where the engine anchors the coordinate. That separation is the point: the reading and the checking stay independent, so agreement between them is worth something.

description is where you actually steer the model: plain-language instructions for what to capture and how. And type: "array" with children is how you pull repeating line items — one child schema, many rows, each row addressable as line_items[0], line_items[1] and so on. (We go deep on that in extracting line items from invoices.)

Going async: batch uploads, jobs, and webhooks

POST /ocr/fields is synchronous and perfect for a single invoice in a request/response loop. It holds the connection open while the page is read, and processing is capped at 180 seconds — past that you get 504 with error.code: "ocr_engine_timeout", and the call is not charged. Density rather than pixel count is usually what pushes a document over the ceiling, so the fix is one page per image, or the async path below.

For a folder of invoices, post them to a sheet with POST /upload (multipart files, repeated, up to 20 per request). By default it returns immediately with a jobs array:

{ "path": "...", "jobs": [ { "uniqueKey": "...", "jobId": "...", "status": "pending" } ] }

You then learn the outcome two ways: poll GET /jobs/{jobId}, or register a webhook. Webhooks are one URL per space, HMAC-SHA256 signed via the X-Spaceocr-Signature header. The events you'll care about are upload.received, item.created, ocr.completed (with data.result carrying the extraction in the same values / cells / review / image shape) and ocr.failed. Always verify the signature before trusting a payload.

Idempotency, request tracing, and rate limits

A few headers make a production pipeline safe to retry:

Rate limits are 60 requests/min per key and 600 requests/min per uid. Exceed them and you get 429 with error.code: "rate_limited" and a Retry-After header carrying the wait in seconds — back off on that value rather than retrying straight away.

For capacity planning, observed latency across production traffic sits around 7.2s at p50 and 10.5s at p90. That is a measured distribution, not an SLA — dense, many-field invoices land above it.

From extraction to a queryable sheet

Once invoices are extracted into a sheet, you don't re-run OCR to read them back. GET /view runs server-side queries over stored rows — where, sort, select, limit, offset — with no charge and no re-extraction. Each row comes back in the same values / cells / review / image shape as a direct call; add boxes=0 to drop the cells map for a leaner payload. From there you can export to CSV (UTF-8 BOM, so Excel and CJK text open cleanly) — see turning scanned documents into CSV.

Pricing

POST /ocr/fields costs $0.05 per call, and POST /upload is $0.05 × N images. Failures are not charged — a 400 invalid_image and a 504 ocr_engine_timeout never reach billing at all, while a 502 engine error or an ocr.failed event is refunded automatically. Read-only endpoints (GET /space, /view, /jobs, /amount, /health) are free. The free tier is 100 credits/month with no credit card; paid plans start at $19/month for Starter and $39/month for Pro — see pricing for the current grid.

How to extract data from an invoice with the API