Skip to content
Space Invoices Documentation

Supplier Invoice Recognition

Use this guide to extract a supplier invoice file into a draft expense and review the result. This is document recognition (OCR); service-period expense accounting is a separate feature.

Automatic expense recognition supports PDFs up to 8 pages. Split a larger PDF into smaller documents before trying again.

Submit and Review a File

  1. Submit a supplier invoice to POST /expenses/recognitions using multipart field file. PDF, JPEG, PNG, and WebP are supported. Include your API key and entity context.
  2. Save the job and expense IDs from the 202 Accepted response. Poll the job until it reaches ready_for_review, needs_attention, or failed.
  3. Review the extracted draft and any warnings. For needs_attention, inspect the reconciliation differences before applying the values. For failed, inspect error_code and error_message; use the retry endpoint when a retry is permitted.
  4. Review and save the expense separately. Loading extracted values does not save or finalize the expense, and payment suggestions do not create payments.

In sandbox, recognition returns a marked demo invoice (simulation_mode: sandbox_demo). It does not extract the uploaded file or call the recognition provider.

Supplier Rounding

Expense recognition also supports supplier invoices that round VAT once per tax group instead of once per line. This exception requires complete, single-rate, non-reverse-charge tax data: each line net must match its rounded gross-derived base, each tax group must reproduce its summary base and VAT from the group gross, and document totals must match the summary and line gross totals. The normal monetary tolerance is not increased.

For example, a supplier may report €62.26 net and €13.70 VAT, totaling €75.96, while four individually rounded line net values sum to €62.28. When the rounding checks pass, the expense retains the supplier’s €62.26 net and €13.70 summary VAT alongside the original calculated line amounts. Item-based category reports continue to use line net amounts; they can therefore differ from the document summary by the proven rounding difference.

Review Extraction Results

A usable extraction with inconsistent amounts returns needs_attention with totals_mismatch. Automatic application is skipped, and extracted_draft remains available for review. reconciliation.differences identifies document or line amounts that disagree with calculation. In the web app, unchanged drafts can load those values automatically; local edits require confirmation before replacement. Loading extraction does not save or finalize the expense, and payment suggestions remain advisory. A newer saved edit is not automatically replaced by an older extraction.

See the Expenses API for recognition endpoints and response fields.