APIGetting Started

Provenance and validation

What a value in an extracted document means, and which signals ride beside it.

Every figure in a document’s report_data is read off that document. The API does not estimate, impute or model a figure: a form line either prints one or it does not, and the payload says which. This page states what the values mean, where a computed figure is kept apart from a printed one, and which document-level signals the API carries. Field lists per document type are on each object page, for example the Tax Return object.

What a value means

  • null means no figure was read for that line: the document leaves it blank, or prints nothing readable there. Keys are not dropped when the line is blank; they arrive as null.
  • A figure means the document prints it. Zero is a figure: a line that reads 0 on the document arrives as zero, not as null.
  • Money keeps the representation of its document type. Tax returns and personal financial statements carry money as strings of the printed digits; bank statements carry numbers. Each object page states which representation its figures use.

Printed versus computed

Where the API computes a total rather than reading one, the computed figure lives under its own key beside the printed one, never in its place. An aging report, for example, carries the totals the report prints and, separately, the totals summed from its rows, so a report whose printed total does not foot shows both. Each object page names the keys that are computed.

Cross-form checks on tax returns

A tax return read carries tie_signals when at least one exists. Each entry names a line on the return that should agree with a line on an attached form, and carries both figures as printed: a stable code, the return’s figure and the attached form’s figure. A return whose lines all agree, or which carries no attached forms to check, has no tie_signals key at all.

Document-level signals

  • assurance_level on each item of List all extracted documents, and cpa_engagement on balance sheets, profit and loss statements and cash flow statements: the level of accountant involvement the document states for itself.
  • underwritingFlags on a bank statement: the statement-level observations the API raises for review.
  • signals on a financial statement: whether a reporting period could be read from the document, and what dated it when the printed heading did not. The object pages whose families enumerate their codes list them.

Source geometry

The workspace and the embedded review panel show every figure’s position on the page (click a figure to see the source). For an API key, the contract is the figures and the signals above; the page geometry those views use to highlight a source is not part of it.

Why there is no per-field score

A field-level confidence number would describe a guess. These values are not guessed: they are read from a form field or a printed line, so the honest per-field statement is the one the payload already makes with null versus a figure, and the honest document-level statements are the signals listed above. When a printed figure disagrees with another printed figure, tie_signals says so with both figures, which is what an analyst needs to decide.