Invoice & Delivery Note OCR to CSV — A Developer's Guide to the Invoice Data Extraction API

Are you still typing invoices and delivery notes into Excel by hand? The date, the vendor, the pre-tax and tax-included totals, and every single line item — at month's end you stare down a stack of paper and copy the numbers one cell at a time. Somewhere along the way a digit slips, the total doesn't add up, and you start the reconciliation all over again. That's the time we want to give back to you.

You try to copy text out of a scanned PDF and you can't even select it. You run it through OCR and the line items collapse into a single cell, line breaks and columns gone. You open the CSV in Excel and the text is mojibake — garbled — so you can't read the product names. All you wanted was to import it into your accounting software, and you trip at the last step every time. Anyone who works with documents knows this story.

This article is a developer's guide to replacing all of that with a single API call. POST an invoice or delivery-note image to POST /ocr/fields and you get back the vendor, date, total, and each line of the detail table as typed, structured data. Better still, every value that comes back carries the coordinates (box and quad) of exactly where on the source image it was read from, so you don't have to take the extraction on faith — you can check it against the original. We'll walk through the whole path, from the shortest route to a production setup, with curl and Python along the way.

Try it first — no upload, 10 seconds to see it work

Before you write any code, look at the actual output. Below is the result of parsing a real receipt. Hover over a field and it highlights where on the image that value was read from. Invoices and delivery notes behave exactly the same way — every extracted value is tied back to the pixels it came from, and anything that did not check out is listed for review in data.review.flagged.

The flow: source image → extracted sheet → highlighted location → CSV export

At its core, using space ocr comes down to four steps. (1) Send the image of a receipt, invoice, or delivery note → (2) it's extracted into a sheet with fixed columns, one document per row → (3) click a value and the matching spot on the source image lights up so you can verify against the original → (4) export to CSV and import it straight into your accounting software. Let's start with dropping in a single document and watching the fields fill in.

Authentication and base URL

The public API has exactly one base: https://api.space-ocr.com — there's no path versioning like /v1. Each request authenticates with an HTTP Bearer token using a key that starts with spocr_.

Authorization: Bearer spocr_xxxxxxxxxxxxxxxx

A missing header or an invalid key returns 401 (error.code: "invalid_api_key"). 403 is not an authentication failure — it means you touched a resource outside that key's scope, such as a job another key created. Every response carries an X-Request-Id header (formatted req_xxx), so it's worth logging it for support requests. If you want to generate a client automatically, the OpenAPI spec is published at GET /openapi.json.

The shortest path — declare the fields you want

Pass the fields you want as an array of FieldSpecs in fields: vendor, invoice date, document number, and total for an invoice; delivery date, item name, quantity, and unit price for a delivery note. Each name becomes the key in the response JSON, so you can transcribe your own table definition straight into the request. For a form you have never seen, autoFields: true lets the model propose the schema instead. The image goes in as a URL or as pure base64, and imageType says which one it is.

A declaration does not change the extraction. type (number / integer / date), pattern, min / max, and required are never shown to the model, so values comes back the same either way. What a declaration produces is two things: the data.normalized layer, where the same reading is parsed into that type, and the review reasons raised on whatever broke a rule (type_mismatch, out_of_range, pattern_mismatch, missing). For repeating rows, don't count the rows — declare the shape of one with type: "array" and children. How many come back is up to the page, and each child's coordinates are resolved within its own row, so a "quantity" or "amount" heading repeated on every row is never confused across rows.

The shape of the response — every value comes with its source

On success you get back { status: "success", data: { ... } }. data is split into layers so business data and verification never mix.

• data.values — pure business data in exactly the schema you declared. No reserved keys are mixed in, so it can be stored as-is.
• data.cells — a flat, path-keyed coordinate and verification map. Look up a path such as total or items[0].amount and you get that value's box (an axis-aligned { xmin, ymin, xmax, ymax }), quad (four points that follow the document's tilt), verified (the verdict), review (the reasons), and evidence (the cross-check record). Coordinates are integers normalized to 0–1000, and the frame for converting them is data.image, not the file you sent: pixel_x = box.xmin / 1000 × data.image.width.
• data.review — the per-document tally plus flagged, the work list of values worth checking. It's an array of { path, reasons }, and path uses the same grammar as the cells keys, so it's a direct lookup. The count is flagged.length.
• data.normalized — present only when you declared a scalar type, a pattern, or an enum. It's a tree shaped exactly like values, with the leaves parsed into that type.
• data.image — the width and height in pixels of the page as it was actually read, after EXIF orientation is applied. Draw outlines against this, not against the file you uploaded.

The evidence entries — text_match (did the character cross-check pass) and match_ratio (how much of the value was found on the page) — are supporting evidence behind the verdict. Rather than picking your own threshold and scanning every field, take review.flagged as the work list.

The addressee and the issuer sit on the same page

The most awkward error on a Japanese invoice or delivery note is not a misread character. It's the one where the characters are read perfectly and the value is taken from the wrong place. One sheet prints two company names — the addressee and the issuer — and picking the wrong one still passes the character cross-check, arriving as verified: true. Handing your vendor master to enum doesn't separate them either, because both are legitimate registered names.

near and not_near are the declarations that reach this layer. On the addressee company name, declare the vocabulary that should be printed beside the value — near: ["御中", "様"] — and the vocabulary that must not be — not_near: ["登録番号", "TEL", "〒"]. If no occurrence of the value sits near a near term, near_mismatch is raised; if one does but the coordinates landed on a different copy, near_ambiguous; if the value sits beside a term from the issuer block, near_conflict. The arithmetic behind each verdict rides in cells[path].evidence.near and evidence.not_near.

When none of the declared near terms is printed anywhere on the page, the check abstains and says so in review.notes as issue: "near_unresolved" — an office form that never prints 御中 must not be punished for it. Those are exactly the forms where parties get swapped, which is why not_near is the one that reaches them. Where a term may sit inside a printed word is set by match: the default boundary, plus suffix (御中, 様), prefix (〒, TEL), standalone, and anywhere — that's what keeps the 様 inside a job name like 中野様邸増築工事 from witnessing an addressee check. Neither declaration is shown to the model, so the extracted value is unchanged. This does not make the right pick; it makes a wrong pick visible.

Click a value and jump to where it came from

Once values have accumulated in a sheet, clicking one lights up the matching spot on the source image. This is the fastest way to spot-check a batch — instead of scanning the whole document, your eye jumps straight to the right place. You don't have to compare every field: open the ones data.review.flagged raised — characters that didn't agree, a declared rule that was broken, a required value that never came back — and the coordinates in cells[path] point straight at the spot to check.

At scale, asynchronously — batch upload, jobs, and webhooks

POST /ocr/fields is synchronous, ideal for the one-document case you put inside a request/response loop. To process a whole folder of invoices and delivery notes, send them to a sheet with POST /upload (repeating the multipart files). By default it returns a job array immediately.

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

There are two ways to collect the results: poll GET /jobs/{jobId}, or register a webhook. Webhooks are one URL per space, and every event is HMAC-SHA256 signed in the X-Spaceocr-Signature header. The events worth watching are upload.received, item.created, ocr.completed (with the extraction in data.result), and ocr.failed. Always verify the signature before trusting a payload.

Idempotency, request tracing, and rate limits

A few headers make it safe to retry your production pipeline.

Rate limits are 60 requests/min per key and 600 requests/min per uid. Exceeding them returns 429 with error.code: "rate_limited", and the number of seconds to wait comes back in the Retry-After header.

From extraction to a queryable sheet

Once you've extracted invoices into a sheet, you don't need to re-run OCR to read them back. GET /view runs server-side queries — where, sort, select, limit, offset — over the stored rows, with no re-OCR and no charge. Coordinates come back by default; add boxes=0 only when you want a lighter response. For example, where=total>=40000 for just the high-value invoices, or sort=-invoice_date for newest first. From there you can export to CSV (with a UTF-8 BOM, so Excel and CJK open cleanly) and use it to import into your accounting software — see turn scanned documents into CSV and convert receipts to CSV for more. The full spec for every endpoint is in the API docs.

Pricing

POST /ocr/fields is $0.05 per call (tax included), and POST /upload is $0.05 × N pages. Failed scans are never charged — a 400 invalid_image and a 504 over the sync ceiling aren't billed at all, and 502 engine errors and ocr.failed events are refunded automatically. Read-only endpoints (GET /space, /view, /amount, /health) are free. The free tier is 100 credits per month with no credit card required, and Pro is $39/month. The full plan list is on the pricing page.

How to extract invoices and delivery notes with the API