Invoice Parsing API — Supplier Invoices to Structured JSON

Parse your first invoice in one call

Base64-encode the invoice and POST it with your key. You do not have to tell the API that it is an invoice — classification is automatic and comes back in the response `type`. Create a key in the API dashboard; the complete reference lives in the API docs.

curl -X POST https://flowparse.io/api/v1/extract \
  -H "Authorization: Bearer pf_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{ "file": "JVBERi0xLjcK...", "filename": "invoice-4417.pdf" }'

flowparse.io

Every field the API returns

An invoice response carries the header fields finance actually posts against, plus the line-item array. Numbers come back as numbers and dates as ISO-8601 strings, so you never parse a locale-formatted string yourself. Anything genuinely absent from the document is null rather than invented — an omission you can detect is far safer than a plausible guess you cannot.

A parsed invoice, in full

Every response shares one envelope — `{ type, pages, billedPages, data }` — and `data` holds the typed document. That uniformity is deliberate: the validate, export, reconcile and merge endpoints all accept exactly this shape, so your integration stays a short linear pipeline instead of a pile of adapters.

{
  "type": "invoice",
  "pages": 2,
  "billedPages": 2,
  "data": {
    "type": "invoice",
    "data": {
      "supplier_name": "Northwind Supplies Ltd",
      "invoice_number": "INV-4417",
      "invoice_date": "2026-07-14",
      "due_date": "2026-08-13",
      "currency": "GBP",
      "subtotal": 1840.00,
      "tax_amount": 368.00,
      "total": 2208.00,
      "line_items": [
        { "description": "A4 copier paper, 80gsm", "quantity": 40, "unit_price": 23.50, "amount": 940.00 },
        { "description": "Toner cartridge TN-247", "quantity": 6,  "unit_price": 150.00, "amount": 900.00 }
      ]
    }
  }
}

Line items, including the awkward ones

Header fields are the easy part of invoice parsing. Line items are where most tools quietly fail, because a real invoice table is not a tidy grid: descriptions wrap onto two or three lines, a table continues across a page break with the header repeated, discount and freight rows sit between products, and some suppliers put quantity to the right of price rather than the left. Flatten that to plain text and rows fuse together or split apart, and the totals stop adding up.

The engine reconstructs the table from the document's own geometry — the coordinates of every text run — rather than guessing from a flat string. A wrapped description stays attached to its row, a table split across pages is stitched into one array, and a right-aligned figure is not captured by the column to its left. When a scanned invoice has no text layer at all, OCR runs first and the same reconstruction applies to the recognised text.

The practical test is arithmetic: for a correctly parsed invoice the line amounts sum to the subtotal, and subtotal plus tax equals the total. That is exactly what `/api/v1/validate` checks for you, which is why validation belongs in the pipeline rather than in a nice-to-have backlog.

flowparse.io

A quality gate you can branch on

Extraction is only useful if you know when to trust it, so the API ships a deterministic validator. `POST /api/v1/validate` returns a 0–100 score, a letter grade and the individual checks behind it — do the line amounts sum to the subtotal, does subtotal plus tax equal the total, is the tax rate plausible for the currency and country, are required fields present, are any values low-confidence. It is arithmetic and rules, not a second opinion from a model, so it is repeatable.

That turns an unattended pipeline into something you can actually run. Auto-accept the clean grades and post them straight through; route the rest to a human queue with the failing check named, so a reviewer looks at one flagged number instead of re-reading the whole document. The complete rule set is documented on the validation engine, and the AI VAT auditor adds tax-specific review for EU invoices.

curl -X POST https://flowparse.io/api/v1/validate \
  -H "Authorization: Bearer pf_live_xxx" \
  -d '{ "type": "invoice", "data": { ... } }'
# → { "validations": [ { "score": { "value": 96, "grade": "A" }, "checks": [ ... ] } ] }

Extract, check, post — the whole flow

flowparse.io

What you can send it

Suppliers do not agree on a format, so the API takes what arrives. Digital PDFs are read from their text layer exactly, which is the most accurate path. Scans and phone photos go through OCR first. Spreadsheets are read directly, which matters more than it sounds — plenty of small suppliers still email an invoice as an XLSX.

flowparse.io

From JSON to your accounting system

Most pipelines need more than JSON at the end. `POST /api/v1/export` converts a parsed invoice into XLSX, CSV or XML, or into an accounting-specific file for QuickBooks, Xero, Sage, Zoho Books, NetSuite, MYOB, DATEV or 1С. The response is base64, and preview requests are free, so you can wire and test the whole export path before a single billed call.

This is what closes the loop for accounts payable. An invoice arrives by email, your worker posts it to the extraction endpoint, the validator scores it, the export endpoint produces exactly the file your ledger imports, and nobody re-keys a number anywhere in the chain. If your team works in spreadsheets rather than a ledger, invoice PDF to Excel covers the same output in the browser.

flowparse.io

Why generalising beats templates

Traditional invoice capture is a library of per-supplier templates: for each vendor, somebody records where the invoice number sits, where the total sits, where the table starts. It is accurate for the suppliers you have configured and useless for the ones you have not. Every new vendor is an engineering ticket, and every supplier redesign is a silent regression — the template still matches something, just the wrong thing, and a wrong number flows into the books looking perfectly plausible.

An AI invoice parsing API generalises instead of memorising. It knows that the total is the largest tax-inclusive figure near the summary block, that a column of dated rows with amounts is a line-item table, that 'Rechnungsnummer' and 'Invoice No.' and 'Facture n°' name the same field. A supplier nobody has ever configured returns the same clean schema on the first request. Pair that generalisation with the deterministic validation engine and you get breadth and a hard correctness check — the combination most rule-based stacks lack.

flowparse.io

How accuracy is protected, and how you verify it

Accuracy in invoice parsing is not one number — it is a set of habits. Values are typed at the source, so an amount is a number and a date is ISO-8601 rather than whatever the supplier's locale printed. Table structure comes from coordinates rather than flat text, so columns do not bleed into each other. And when a field is genuinely ambiguous, the engine records lower confidence instead of inventing a value, because a null you can see beats a confident wrong number you cannot.

You verify the result rather than trusting a marketing figure. Post any parsed invoice to `/api/v1/validate` and you get the arithmetic checked against itself: line amounts against the subtotal, subtotal plus tax against the total, tax rate plausibility, missing required fields. An invoice that passes those checks is arithmetically consistent with what the supplier printed — a much stronger statement than a vendor's average accuracy claim, because it is computed on your document, not on a benchmark set.

flowparse.io

Multi-currency and multi-jurisdiction invoices

An invoice parsing API that only handles one country is not much use to a company with suppliers abroad. The currency is detected from the document itself and returned as an ISO code, so a EUR invoice and a GBP invoice from the same supplier are never confused. Amounts are normalised from whichever decimal and thousands convention the supplier used — 1.234,56 and 1,234.56 both become 1234.56 — which removes an entire class of silent ten-thousandfold errors.

Tax is returned as an amount rather than an assumed rate, because rates differ by country, by product category and by period, and reverse-charge invoices carry no tax at all. For EU VAT specifically, the AI VAT auditor checks the numbers against the rules that apply, and the VAT number validator confirms a supplier's registration is real. Together these matter most exactly where mistakes are expensive: cross-border purchases that a tax authority may later examine.

Integrate from any language

There is no SDK to adopt and no language constraint: the API is JSON over HTTPS, so any HTTP client works — requests in Python, fetch in Node, HttpClient in .NET, curl in a shell script. The shape is always the same. Base64-encode the file, POST it to `/api/v1/extract`, read `type` and `data`, then branch. Because every endpoint speaks that schema, a thin internal wrapper of extract, validate and export functions is usually the entire integration layer, and it stays valid because the contract is versioned under `/api/v1`.

A clean pattern at volume is a queue plus workers: enqueue each incoming invoice, have a worker call extract then validate, write the result, and notify your own system. Make jobs idempotent on a file hash so a retry cannot create a duplicate bill, cap worker concurrency so one large batch cannot drain your page budget in a minute, and log the billed pages and validation grade with every record for a complete audit trail. The playground runs real requests in the browser if you want to see the shape before writing code.

Processing invoices in bulk

Accounts payable arrives in waves — a quiet Tuesday and then two hundred invoices on the first of the month. Extract each document individually and in parallel across workers rather than assembling one enormous request; per-document calls are independently retryable, and a single failure does not cost you the batch. When you need the results as one workbook rather than one record per invoice, `POST /api/v1/merge` consolidates up to 100 documents into a single reconciled Excel file, the API-side equivalent of Smart Merge.

Two limits are worth designing around from the start. Documents are capped at 20 MB per request, which comfortably covers even long scanned invoices. And your page budget is finite, so a runaway retry loop is the one failure mode that costs real money — cap concurrency, back off on errors, and watch per-key usage in the dashboard. For a browser-side equivalent of the same volume workflow, see batch processing.

flowparse.io

Status codes and what to do about them

Standard HTTP codes make error handling short, and no call returns data you were not billed for or bills you for data you did not get. The two you must handle explicitly are 429 and 503: the first means your page budget is exhausted and tells you the exact shortfall, the second is transient and deserves exponential backoff rather than an immediate retry.

What it costs and what is free

Extraction and file exports bill per page from your page balance. Validation, reconciliation and export previews are free, which means you can build and test an entire integration — the schema, the branching, the export mapping — before you enable a single billed call. Plans and page allowances are on the pricing page, and per-key usage, request counts and cost are visible in the dashboard.

flowparse.io

What teams build with it

Where invoice parsing fits in AP automation

Invoice parsing is the capture step of accounts payable automation, and it is the step everything downstream depends on. Three-way matching cannot compare an invoice to a purchase order and a goods receipt unless the invoice is data. Duplicate detection cannot spot the same bill submitted twice unless supplier, number and amount are all fields. Approval routing cannot apply a threshold rule unless the total is a number. Get capture wrong and every clever rule after it operates on noise.

That is why the validator matters as much as the parser here. A pipeline that posts whatever comes back will eventually post a wrong figure with total confidence; a pipeline that gates on arithmetic consistency will stop and ask. Once capture is reliable, the rest follows naturally — see three-way matching for the PO side, duplicate payment detection for the control, and AP automation for the whole picture.

flowparse.io

How your documents are handled

Invoices carry commercially sensitive information — who you buy from, at what price, on what terms — so the handling matters as much as the parsing. Requests travel over HTTPS. Keys are stored hashed and can be rotated or revoked per environment, so a key in a staging system is never the key in production. Uploaded files are processed to produce the response and are not retained as downloadable documents, and your requests are not used to train models.

On your side, two habits do most of the work. Keep the raw file and the parsed JSON out of application logs, since a log aggregator is usually the least protected place a document ends up. And store only the fields you actually need — if your ledger never uses the supplier's bank details, do not persist them. Our security page documents the platform side in full.

Watching cost and quality over time

Running invoice capture at volume means watching two numbers, and they fail in different ways. Spend is the obvious one: every API key tracks its own requests, pages and cost, so you can see what each integration consumes and spot anomalies quickly. A sudden spike is almost always a retry loop or a malformed batch rather than genuine growth, and catching it the same day rather than at the end of the month is the difference between a note and an incident.

Quality is the number people forget. Log the validation grade with every parsed invoice and chart the auto-accept rate. A falling auto-accept rate is an early warning that input quality has changed — a new supplier sending photos instead of PDFs, a scanner set to a lower resolution, a mailbox rule pulling in the wrong attachments. Watching that trend lets you fix the input before bad data reaches the books, which is far cheaper than correcting entries afterwards.

flowparse.io

Building the integration before you spend anything

Because validation and export previews are free, the sensible order is to build the whole pipeline against them first. Parse a handful of real invoices, keep the JSON, and develop your branching, your export mapping and your review queue against those fixtures. Your test suite then runs on stored responses rather than live calls, which makes it fast, deterministic and free — and it keeps working when you are offline.

Test the unhappy paths deliberately, because they are what break in production. Send a deliberately unreadable scan and confirm you handle 422 without creating a half-written record. Simulate 429 and confirm your queue pauses and resumes rather than dropping documents. Feed an invoice whose totals genuinely do not add up and confirm it lands in the review queue instead of the ledger. The playground is useful for exploring the shape interactively before any of this.

Using it without writing an integration

You do not need an engineering team to get value from an invoice parsing API. Automation platforms can call it directly: Zapier through Webhooks by Zapier, Make through its HTTP module, and n8n through the HTTP Request node. In each case the pattern is the same — a trigger fires when an invoice lands in a mailbox or a cloud folder, the file is base64-encoded, the platform posts it to `/api/v1/extract`, and the parsed fields flow into a spreadsheet, a ledger or a database row.

Each platform has its own quirks, so we have documented them separately: Zapier, Make and n8n. If you would rather not automate at all, the browser flow at extract invoice data does the same job by upload, and batch processing handles a folder at a time.

flowparse.io

Getting this right in production

Treat the parsing API as one step in a pipeline rather than a black box that returns truth. Validate every invoice and branch on the grade so a human only ever sees genuinely ambiguous documents. Prefer the digital original over a scan of it whenever the supplier will send one, because a text layer is read exactly while a scan is recognised. Persist the validation score and `billedPages` alongside each record so you have a queryable trail of what was captured, what it cost, and what was auto-accepted versus reviewed.

Operationally: run extraction behind a queue rather than inline on a web request, make jobs idempotent on a file hash, handle 429 by pausing rather than hammering, and keep documents and parsed JSON out of logs. Done this way, invoice capture stops being a data-entry function and becomes an unattended part of the month — with an audit trail good enough to show an auditor how any given number reached the ledger.

Where to go from here

If you also process statements, the bank statement API covers that path and the bank statement OCR API covers scans. For the generic contract across every document type, see the document extraction API and the PDF to JSON API. To produce spreadsheets rather than JSON, the PDF to Excel API returns a finished workbook. And for a complete worked integration with batching and error handling, follow the guide to parsing bank statements with an API — the pattern is identical for invoices.

flowparse.io

Frequently asked questions

Related