Skip to navigation
APIGetting Started

Provenance and validation

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

Use extraction values and validation signals to review a document’s data. This page explains missing values, calculated totals, and source references. Each document’s object reference lists its fields, including 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 is a string with exactly two decimals on every document type ("9200000.00", "-1250.50", "0.00").

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 documents, and assurance on the financial statements and supporting tables: the level of accountant involvement the document states for itself.
  • underwriting_flags 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.

Reviewing results

Use tie_signals to review differences between a return and its attached forms, and the document-level signals above to review the document as a whole. Each check runs when the document carries the forms and figures it needs.