Finance Operations

How a bill moves through Finance on your instance: reading and human review, matching to purchase orders, approval, segregation of duties, budgets and their own approval, the general ledger and month-end close, and the journal export for an outside accounting system. The flow ends when you mark a bill Paid. Zonitix does not pay bills and nothing here moves money.

What It Does

Finance makes sure that raising, approving and paying a spend cannot all be done by one person, and that spend that breaches a budget cannot be approved silently. Two things are worth being precise about, because they are easy to overstate.

If something here is not working as you expect, start with When something goes wrong.

The Finance Workspace, Tab By Tab

In the app, almost everything on this page is one screen: the Finance workspace, opened from Finance → Finance in the sidebar by anyone holding view_finance or manage_finance. It has fifteen tabs, and a tab is shown only to people whose role includes a permission it needs. The sidebar’s Bills, Approvals and Vendors items are shortcuts to those tabs. Budgets opens the budgets screen, which a department manager holding only the budget permissions can also reach. An employee whose role includes only submit_invoice does not get the workspace: they upload from My Work → Submit Invoice and see only their own bills.

Before The Ladder — Extraction & The Human Review Gate

An uploaded invoice is read on your instance by a heuristic extractor, optionally refined by a local LLM. The refinement runs only when the heuristic’s confidence is below 0.8, and it is limited in what it may change: a total is accepted only when the digits of its whole-number part appear in the source text, a tax amount needs the same check, must be below the total and is taken only when the heuristic found no tax, and an invoice number is accepted only when it appears in the text and the heuristic found none. A vendor name is accepted without a text check, but only when the heuristic found no vendor at all. Confidence is raised (to at most 0.9) only when the total itself was re-read, so a vendor-, tax- or number-only refinement never lifts an invoice out of review. The pass is controlled by the finance.llm_extraction setting (default on) and does not run when local AI is disabled on the instance (ENABLE_LOCAL_AI). Nothing about the invoice leaves your instance. The reading itself is described step by step under Reading Bills (OCR Extraction).

The upload screens accept PDF, DOCX, PNG and JPG files up to 10 MB. The API route behind them (POST /api/parser/parse, gate: manage_finance or submit_invoice) additionally accepts .xlsx and .txt; the older .xls format is refused. A byte-identical copy of a file already on the instance is refused with 409 before any reading happens. Spreadsheets of many invoices go through the CSV bulk import described under Bulk Operations, Import & Export below.

Bills from a connected AWS account can be pulled in without uploading them by hand. POST /api/auth/aws-resources/{providerId}/sync-invoices (gate: manage_compliance) fetches the account’s invoice PDFs for the last six complete months and passes each one through the same parse route, so they are read, held or drafted, and approved exactly like an uploaded bill. An invoice that is already stored (the same file, or the same vendor and invoice number) is skipped, so running the sync again does not duplicate anything. The run is written to the audit log as CLOUD_INVOICES_SYNCED, on success and on failure. The matching Azure route reads cost data only and creates no invoices.

Extraction produces a confidence score. A clean read lands in Draft and is submittable. The document is instead held in NeedsReview, and kept out of committed spend, when any of five things is true: the confidence is below the review floor (the finance.review_confidence_floor setting, default 0.80); the amount’s thousands/decimal separator is ambiguous; the invoice date is missing or its day/month order is ambiguous (with no date, the upload date is stored as a placeholder); there is no exchange rate for the invoice’s currency; or it looks like a duplicate of an existing invoice (same vendor, amount and date). submit refuses that state, so a held invoice cannot be paid without a human first confirming it.

The exit is PATCH /api/parser/finance/documents/{id}/review (gate: manage_finance or submit_invoice). Each field change is audited before→after and the base amount is recomputed. A manage_finance reviewer sending { "commit": true } releases a NeedsReview document to Draft; the release returns 409 while an ambiguous amount or a flagged invoice date is unconfirmed (the reviewer clears each flag by saving that field in the same call or an earlier one) and 400 while the currency still has no rate. A submit_invoice-only user may correct an invoice they uploaded themselves, but can never release it — any change they make sends it (back) to NeedsReview for finance to confirm, and someone else’s invoice returns 403. A reviewer can also clear the hold without editing fields by calling the workflow endpoint with the clear_review action (manage_finance), which applies the same gates: 409 for an unconfirmed amount or date, 400 for a currency with no rate.

The Workflow Endpoint & Who May Do Each

One endpoint drives the five transitions: POST /api/parser/finance/documents/{id}/{action} where action is one of submit, approve, reject, pay, clear_review. An unknown action returns 404; a missing document returns 404; an illegal transition (e.g. paying a Draft) returns 400. On success the body is { "success": true, "approvalStatus": "…" }.

submit, approve and reject return 409 when the invoice is dated in a locked accounting period; pay is still allowed after the period is closed, because the payment is booked in the current period.

The permission gate is amount-aware. Below the high-value floor (the finance.high_value_floor setting, default 25,000 in base currency — the same single floor the segregation-of-duties rules use) a manage_finance holder may approve or pay. At or above it, the dedicated approve_invoice / pay_invoice permission is required — manage_finance alone no longer suffices. Users holding the administrator role bypass the permission check entirely (but not the segregation-of-duties identity checks below, which compare user ids). Holding pay_invoice also puts an account on the MFA floor, so it is asked for a second factor at every sign-in whatever its groups are set to; see Forcing MFA By Group.

Invoices: List, Detail & Self-Service

Two audiences read invoices. Finance roles (view_finance or manage_finance) read the whole ledger. An employee holding only submit_invoice reads only the invoices they uploaded themselves, through the my-documents routes; asking for someone else’s returns 404, the same answer as an invoice that does not exist.

The timeline route is the employee’s view of the audit trail, and it is a whitelist. It returns only these steps: uploaded, corrected by the uploader, checked by finance, confirmed by finance, sent for approval, an approval step, approved, rejected and paid. Each step carries a label and a time; approval and rejection steps also name who decided, and, while the invoice is still rejected, the rejection step carries its reason. Internal finance actions (allocation, a budget override, a waived match exception) and the audit entry’s detail text are never returned.

Segregation Of Duties — The Identity Rules

When SoD is enforced, the transition functions compare the acting user’s id against the ids already recorded on the invoice, and refuse a self-serving action with a 403. The exact rules:

• Approve: the acting user must differ from submitted_by (the submitter cannot approve their own request) and from userId (the uploader cannot approve the invoice they uploaded).
• Reject: the acting user must differ from submitted_by (the submitter cannot reject their own request).
• Pay: the acting user must differ from every approver recorded on the invoice (all of them under an N-of-M rule, not only the last), from userId (the uploader) and from submitted_by (the submitter). An approver, the uploader, or the submitter cannot also mark it paid.

Enforcement is governed by the enforce_sod finance setting — the Enforce segregation of duties switch in Finance → Settings, which only a holder of manage_security can change. It is on by default: only the literal value false disables it, and when disabled the service emits a warning log Segregation of duties is GLOBALLY DISABLED. The invoice amount used for the floor check is amount_base (falling back to amount).

Finance Settings — Who May Change A Control

The controls on this page are tuned in Finance → Settings, backed by one audited endpoint that accepts only a fixed list of keys (an unknown key returns 400). Each write records old → new as a setting_changed audit entry. The settings that are the control — enforce_sod, finance.high_value_floor, match.tolerance_pct (clamped to 0–0.5) and match.require_grn — need manage_security, so a finance operator cannot weaken the rules they work under. The rest need manage_finance: the review confidence floor, LLM-assisted extraction on/off, the digest (enabled, recipients, cadence), the fiscal-year start month, the budget warning and over thresholds, and the cloud cost anomaly threshold.

Configurable Approval Rules — Amount-Tiered N-of-M

How many approvers an invoice needs is not a single fixed $25k rule — it is a configurable set of amount bands. Each rule carries a minAmount, an optional maxAmount (omit it for an open-ended top band), and a requiredApprovals count. On approve, the service picks the highest active band the invoice’s amount falls into and requires that many distinct approvers before it advances Submitted → Approved. A band covers minAmount inclusive up to maxAmount exclusive, so an invoice of exactly a band’s maximum falls into the next band; maxAmount must be greater than minAmount. Where active bands overlap, the one with the highest minAmount applies. With no matching band the requirement is 1 (and a rule-lookup error also fails open to 1, so a bad rule can never wedge approvals). Changing the rules is a policy change: it needs manage_finance_policy, not manage_finance, so an AP operator cannot lower the approver count on their own invoices. A refused attempt is itself audited. A rule name is at most 80 characters and requiredApprovals at most 10; an invalid rule returns 400.

Distinctness is enforced twice: the same user cannot approve an invoice twice at the application layer, and a database partial-unique index on (doc_id, actor_id) backstops the race with a 409. Approvals are counted per submission round: only approvals given since the invoice was last submitted count, so after a rejection and a re-submission the earlier approvals no longer fill the quota, and someone who approved the earlier round may approve the new one. Below quota the invoice stays Submitted in the approvals queue; GET /finance/documents/{id}/approvals reports progress as distinct-approvers-so-far vs required. This N-of-M band engine is separate from the $25k SoD floor above: the floor decides when the identity checks and the dedicated approve_invoice/pay_invoice permissions are force-enforced; these rules decide how many distinct approvers a given amount needs.

2-/3-Way PO Matching Blocks Approval

An invoice that references a purchase order must reconcile to it. Header matching always compares the invoice total against the PO total within a configurable tolerance (match.tolerance_pct, default ±2%, settable between 0 and 50%). When both the invoice and the PO carry line items, line matching additionally checks quantity and unit price per line; where goods-receipt lines exist, received-versus-ordered is checked (a true 3-way match), and with strict 3-way enabled (match.require_grn) a PO-referenced invoice with no receipt is flagged. A variance beyond tolerance — or a referenced PO that is missing — opens a match exception that blocks approve with a 409 until the exception is resolved or explicitly waived with a reason.

Matching is fail-open by design: an invoice with no PO number is not_applicable and is never blocked, so a legitimate non-PO invoice always flows. A missing block is therefore not proof a PO existed and matched.

A purchase order is itself a commitment against a budget, so it is checked when it is created: a PO whose base-currency total exceeds what the matching budget has Available is refused with 409 unless the body carries budget_override: true, in which case it is created and a po_budget_override audit entry is written. When a PO has line items its total is derived from them (quantity × unit price); a total supplied alongside lines is ignored. A PO in a currency with no exchange rate returns 400. Open POs are listed in the PO register and can be closed, cancelled or re-opened.

The Budget Block & The Audited Override

On approve (only), the service checks the invoice against every current budget its spend rolls into. It walks vendor, then category, then department, then cost-center, then global scope; monthly period first, then annual. The rule depends on whether the invoice references a purchase order:

• No PO (net-new spend): blocked when the invoice amount exceeds the budget’s Available — budget minus actual, minus open PO commitments, minus open spend requests. This fires before the line is over, on the invoice that would take it over.
• PO-backed: the PO already holds that budget as a commitment, so approving the invoice only moves it from committed to actual. These are blocked only when the line is already Over.

Either way the approval is refused with 409 and a human-readable detail naming the line. Purchase orders are checked the same way when they are created (see PO matching above).

To override, send { "budget_override": true, "override_reason": "…" } in the body. An override relaxes a control, so it needs the dedicated approve_invoice permission at any amount (manage_finance alone returns 403) and a non-empty override_reason (400 without one). The approval then proceeds and an extra audit entry, action budget_override with detail Approved OVER BUDGET (…) — reason: …, is written alongside the normal approved entry. The block is deliberately fail-open: if the budget calculation itself throws, it returns no block and logs a warning — a budget-calc bug must never wedge the approval workflow, so a missing block is not proof no budget applied.

A frozen budget is different. If the invoice rolls into a budget scope that finance has frozen, approval is refused with 409 and budget_override does not get past it — the hold has to be lifted first (see Budget Lifecycle below).

Allocation Is Frozen After Submit

Cost-center, department, project, GL code, currency and any custom allocation fields are set through PATCH /api/parser/finance/documents/{id}/allocation (gate: manage_finance). Because currency drives amount_base, and cost-center drives which budget the spend rolls into, these are frozen once the invoice enters the workflow. A PATCH against an invoice in Submitted, Approved or Paid state returns 409; re-allocation is permitted while Draft, Rejected or NeedsReview. An invoice dated in a locked accounting period is also refused with 409, whatever its state. Only the keys you send are changed. A glCode that is not in the chart of accounts returns 400, as does a currency with no exchange rate; customFields keeps only keys defined in your allocation custom-field schema. A missing document returns 404.

Budgets (CRUD)

A budget targets a scope (global, vendor, category, department or cost_center) for a period: YYYY-MM is a calendar month, YYYY is a fiscal year whose start month is the finance.fiscal_year_start_month setting (default 1, the calendar year). A budget may be entered in any currency that has an exchange rate (400 otherwise); all comparisons are done in base currency. Actuals are summed live in base currency, and count only committed spend — invoices in NeedsReview, Draft, Submitted or Rejected are excluded (a null approval status is treated as committed). Thresholds are configurable: a budget’s own warnPct / overPct win, otherwise the global finance.budget_warn_pct / finance.budget_over_pct settings apply (defaults 80% and 100%). Alongside actual, each row reports committed (open purchase orders) and available (budget minus actual, commitments and open spend requests).

Budget access is its own permission family, separate from invoice handling. Reading needs any of view_finance, manage_finance, view_finance_consolidated, manage_all_finance_budgets, approve_finance_budget, view_finance_budgets or manage_finance_budget; writing needs manage_finance, manage_all_finance_budgets or manage_finance_budget. The list is scoped to the caller: finance and consolidated roles see every budget, while a department manager holding only the budget permissions sees their own and their department’s, may create budgets only for their own department (the owner is stamped server-side), and may edit only budgets they own (403 otherwise).

Budget Lifecycle — Submit, Approve, Reforecast, Freeze

A budget is more than a number to compare against. It has its own approval lifecycle, shown on the Budgets page in the Finance section of the sidebar and on the Budgets & Chargeback tab of the Finance workspace. A new budget starts as Draft. Its owner submits it; an approver approves or rejects it; approval locks it as the baseline. The read and write permission lists are the ones given under Budgets (CRUD) above.

• Submit: only a Draft or Rejected budget, and only your own (409 / 403 otherwise).
• Approve / reject: an owner cannot approve their own budget. The approver must be either a finance-level approver or the owner’s manager; anyone else gets 403, and the refusal is audited. The one exception is the administrator role, which is not held to this check: an administrator can approve a budget they own, and that approval is flagged on the audit trail as budget_admin_self_approval. Reject requires a reason (400 without one).
• Reforecast: a locked budget is not edited in place. Reforecasting creates a new Draft version; earlier versions stay readable.
• Unlock: needs manage_finance_policy. Any edit after an unlock sends the budget back to Submitted for re-approval, and the person who edited it cannot approve their own edit. Until it is re-approved, an increase does not take effect — spend is still measured against the previously approved amount — while a decrease applies immediately.
• Freeze: a hold on the budget’s scope. While frozen, invoice approvals that roll into it return 409 and no override gets past it.

Budget Lines, Alerts & Reporting

A budget can be built bottom-up from line items, each a flat amount or a driver (quantity × unit cost), and anyone who can see a budget can comment on it. A threshold sweep runs hourly and raises an alert when a budget reaches its warning threshold, is on pace to exceed its amount, or goes over; alerts are scoped to the caller the same way budgets are, and can be acknowledged. Every budget action writes to the finance audit trail, with its own filtered export.

Spend Requests — Asking Before You Spend

A spend request asks for budget before the purchase happens. While it is Pending or Approved its amount is held against the budget: it is subtracted from Available, so the invoice and PO checks above see the decision before any invoice exists. Rejecting it, or marking it Fulfilled once the real PO or invoice has taken over, releases the hold. Anyone who can see a budget can raise a request against it; the approver follows the same rule as a budget approval, and a requester cannot approve their own request (403). The administrator role is exempt from both checks, so an administrator can approve a request they raised themselves.

Budget Transfers

A transfer moves budget from one budget to another and normally takes two people: the requester cannot approve or reject their own transfer (403). The number of distinct approvers comes from the same amount-tiered approval rules that govern invoices. A department-level mover may only transfer between budgets inside their own scope; a transfer at or above the high-value floor must be approved by someone holding manage_finance or manage_all_finance_budgets. The administrator role is exempt from both the requester check and the high-value rule, so an administrator can approve or reject a transfer they requested themselves. A locked budget cannot be changed by a transfer (reforecast it instead), and a transfer the source cannot fund returns 409. Budgets in different currencies are converted at the configured rates; a missing rate returns 400.

Systems & Cloud Cost Against A Budget

On the Systems tab a budget owner can claim a system from a connected provider and, optionally, attach it to one of their budgets. A budget whose authoritativeSource is cloud or both then counts that system’s billed cost toward its actual. Cloud cost anomalies are flagged when a system’s cost rises month over month by more than the finance.cloud_anomaly_pct setting (default 30%), whether or not a budget threshold was crossed.

Chargeback (Spend By Dimension)

GET /api/parser/finance/chargeback (gate: view_finance, manage_finance, view_finance_consolidated or manage_all_finance_budgets) allocates base-currency spend across a dimension. It is an organisation-wide view, so a department manager holding only the scoped budget permissions cannot call it. Like every other roll-up it counts committed spend only — invoices that are Draft, Submitted, Rejected or held for review are left out, so the totals tie to the dashboard and to budget actuals. The dimension query param is one of cost_center (default), department, project, category; an unrecognized value falls back to cost_center. An optional period (YYYY-MM / YYYY) narrows the window. Rows with no value on that dimension are grouped under Unallocated.

Vendors & Vendor Merge

Raw OCR vendor strings collapse onto canonical vendor records (matched by canonical name or alias, auto-created on first sight). Merge folds one vendor into another: it repoints the loser’s invoices to the keeper, absorbs the loser’s aliases (plus its old canonical name as a new alias), and moves the loser’s vendor-scoped budgets onto the keeper (dropping one where the keeper already has a budget for that period). Closed periods are never rewritten: an invoice dated in a locked accounting period keeps its original vendor and is reported as skipped. If any were skipped, the loser row is kept and marked as merged into the keeper, so new documents still land on the keeper; otherwise the loser row is deleted.

Base Currency & FX Recompute

Every invoice stores its native amount + currency; amount_base is the normalized value all roll-ups sum. FX rates are set by an administrator on your instance (no external FX API). POST /api/parser/finance/currency (gate: manage_finance_policy — manage_finance alone returns 403, and the refused attempt is audited) can set the base currency (baseCurrency) and/or upsert a rate (code + rateToBase), then recomputes normalized totals. A non-positive, non-finite, or out-of-band (outside 1e-6…1e6) rate is rejected with 400 before anything is persisted — a bad rate would otherwise re-value the whole ledger.

Trends, Open Commitments & SaaS Spend

Three read-only views sit on top of the ledger, on the Trends and SaaS Spend tabs of the Finance workspace. All of them are computed from data already on your instance, in base currency, from committed spend.

• Variance and category trend: this month against last month and against the same month last year, the categories that moved most, and committed spend per category over the last 3 to 24 months.
• Open commitments: the value on purchase orders that are not closed or cancelled and have not been invoiced yet — what is committed but not yet billed.
• SaaS spend: committed spend per app (canonical vendor), its owner, seats and cost per seat where usage is known, and a renewal timeline grouped into the next 30, 31–60 and 61–90 days. Renewal dates come from the contractRenewal date you set on the vendor; an app with no date is not on the timeline. An annual budget set on an app is an ordinary vendor-scoped budget, so it also appears on the Budgets tab and takes part in the budget block.

The connectors list shows which providers can supply billing data. Only AWS and Azure feed billing data today. The other providers in the list are shown as available, not as a working feed, and a provider connected only for sign-in or provisioning is not reported as supplying spend.

General Ledger, Month-End Close & Journal Export

Committed spend is coded to a general ledger against a chart of accounts (GET / POST /api/parser/finance/gl-accounts; a duplicate account code returns 409). Locking an accounting period (POST /api/parser/finance/close/{period}, period as YYYY-MM) generates balanced double-entry journals for that period’s committed invoices — a debit to expense, an input-tax leg where applicable, and a credit to accounts payable — and marking an invoice paid posts a settlement journal that debits AP back down, so the AP balance nets to zero rather than growing without bound.

Each invoice posts to the GL code set on it through the allocation endpoint (glCode, validated against your chart of accounts once one exists). An invoice with no GL code posts to the catch-all expense account 6000; the other default accounts are 2000 (accounts payable), 1000 (cash) and 1400 (input tax). The close status reports how many committed invoices are still uncoded — an advisory, not a blocker. The settlement journal is a cash event, so it books to the current period, and marking an invoice paid is deliberately still allowed after the invoice’s own period has been locked.

Close is fail-safe: it refuses to lock a dirty period — one that still holds NeedsReview invoices, invoices awaiting approval, or open match exceptions — unless the lock is explicitly forced with { "force": true, "reason": "…" }. A forced close without a written reason returns 400, and the reason lands on the audit trail. Closing needs the dedicated close_finance permission; manage_finance alone returns 403, which keeps locking a period separate from approving and paying. Once locked, no write may touch an invoice dated in that period (the same freeze the allocation and FX endpoints rely on). The period’s journals export as a CSV (GET /api/parser/finance/close/{period}/journals.csv) for import into an external accounting system. The format query parameter picks the layout: generic (default), quickbooks (QuickBooks General Journal import columns) or xero (Xero Manual Journal import columns).

A locked period is never reopened. A correction after close is posted as a balanced adjusting entry into the current open period through POST /api/parser/finance/adjustments with debitGl, creditGl, amount and a mandatory reason. It returns 400 for a missing reason, identical or unknown accounts, or a non-positive amount, and 409 if the current period is itself locked. GET /api/parser/finance/reconciliation?period= compares invoice actuals with what was posted to the GL for a period.

GL sync today is file-based. The sync endpoints (GET /api/parser/finance/gl-sync; set with PUT /api/parser/finance/gl-sync/connector; run a period with POST /api/parser/finance/gl-sync/{period}; the two writes need manage_finance, the status read also allows view_finance) work with the manual connector, which is the default: running it stamps each unsynced journal with an external_ref and marks it exported, and you load the journals CSV into your accounting system yourself. Nothing is sent over the network. The connector picker also lists quickbooks, netsuite and xero, but those API connectors are not built: selecting one and running a sync returns 400 and pushes nothing, rather than silently doing nothing. What exists for QuickBooks and Xero is the journal CSV in their import layout (the format parameter above). The run is idempotent: a journal that already carries an external_ref is never stamped again, so a re-run can’t mark or export the same journal twice.

Ask The Ledger — SQL-Grounded, Local LLM Fallback

POST /api/parser/finance/ask (gate: view_finance / manage_finance) answers a natural-language question about your spend. A deterministic SQL layer answers the common numeric questions exactly against committed spend in base currency — so a dollar figure is never hallucinated by a small local model. Only when no exact aggregate applies does it fall back to the local Ollama model on your instance; either way, no invoice or spend data is ever sent to an external model. A missing question returns 400. In the app this is the AI Insights tab of the Finance workspace: type the question in the box and click Ask.

Audit Trail & Digest

Every workflow action, budget change, vendor edit, currency change, allocation and delete writes an append-only finance audit entry, and each is also mirrored into the app-wide Audit & System Logs as a FINANCE_<ACTION> event. The audit endpoint is the record an inspector reads back to confirm who did what.

The scheduled digest email is off by default. It is sent only when three finance settings say so: finance.digest_enabled, finance.digest_recipients and finance.digest_interval_hours. It goes out through the email transport configured on your instance, and only to recipients who are active users.

Bulk Operations, Import & Export

One action can be applied to many invoices in a single call. POST /api/parser/finance/documents/bulk takes an action (submit, approve, reject, pay, clear_review, allocate or delete) and up to 500 ids. Bulk is not a shortcut around the controls: every invoice is processed on its own with the same permission, segregation-of-duties, budget, match, period-lock and allocation-freeze checks as the single-invoice endpoints. There is no all-or-nothing transaction — one failing row never undoes the others — and the response lists the outcome of every row, so a partial success is visible.

Invoices can also arrive as a CSV file rather than one document at a time. Each row needs a vendor (header vendor, supplier, payee or name) and an amount (amount, total, amount (base) or cost); a row missing either is skipped. The optional columns are currency (or ccy), date (or invoice date), category, cost center, department (or dept), project, the vendor’s invoice number, and a display name (filename, invoice id or reference). Headers are matched case-insensitively, and a semicolon-delimited file is detected from its header row. status is not an import column: whatever a file puts there is never applied (a value other than pending or draft is counted in the audit entry), and every imported invoice goes through submit, approve and pay like any other.

• Invoice number. Read from a column headed invoice number, invoice_number, invoicenumber, invoice no, invoice no., invoice #, invoice num, invoice id, invoice_id, invoiceid, bill number, bill no or bill no. (an invoice id column therefore sets both the number and the display name). A row whose vendor + invoice number matches an invoice already on file that is not rejected, or an earlier row of the same file, is skipped and reported as a duplicate, so importing the same file twice does not double it.
• Currency. A row with no currency is booked in your base currency and flagged. A row whose currency has no exchange rate is skipped.
• Date. An empty date cell becomes the import date, with no flag. A date that is present but cannot be read, or whose day/month order is ambiguous, imports the row held in review; an unreadable date uses the import date as a placeholder until a reviewer confirms it.
• Likely duplicates. A row with the same vendor, amount and date as an invoice already on file, or as an earlier dated row of the same file, is imported held in review as a likely duplicate, not dropped. A row that carries an invoice number is compared only with invoices that have none.
• Starting state. A row is held in NeedsReview when its amount separator is ambiguous, its date is flagged, or it is a likely duplicate. Every other row starts as a Draft.
• Response. imported, skipped, errors (the first 50), currencyDefaulted, amountAmbiguous, dateHeld, duplicatesSkipped and duplicatesHeld.

Data Objects (Typed Fields)

In plain words: a call to the API answers with objects such as an invoice, a vendor, a purchase order or a budget. This section lists what is inside each one: every field, its type, and whether it can be empty. Open an object to see its fields. The routes that return them are in the API reference under Finance & Document Parser and the three groups whose names start with Finance:, where a capitalised name in a row’s returns line is one of these objects.

• Types. integer, number, string, boolean, object and arrays written as string[]. string (date-time) is ISO 8601; string (date) is YYYY-MM-DD. A type followed by a colon and values separated by | takes only those values. A capitalised type is another object in this list.
• The third column. “nullable” means the field can be null; “optional” means the key can be missing; “no” means neither. Do not fail on a field you do not recognise: a reply can carry fields beyond these. A card marked “request body” is what you send, not what comes back: its third column is headed Required, where “required” means the field must be sent and every other field is optional.
• Money is a number here. The finance service sends every amount as a JSON number, such as 1250.0. In other modules check the type on each object: some send a stored decimal as a string.
• Two date forms. Invoice.date and Invoice.renewalDate are display text (“Oct 10, 2026”, or “N/A”); read Invoice.dateIso in code. PurchaseOrder.orderedDate is display text too, or null, and the list has no ISO form of it.