Audit-grade citations

Every extracted value carries a page reference and a bounding box pointing back to where it came from in the source document. When a controller asks "show me the receipts", the answer is a click away.

Audience: builders

Why you're here

Your AP controller is reviewing a sampled invoice as part of a SOX walkthrough. The extracted total is $14,820.50. The controller's question is "where did that number come from?" Your shipping team is auditing a stuck shipment: the extracted consignee does not match the order of record, and the question is "did the agent misread, or did the carrier ship to the wrong party?" Your quality team is responding to a regulator: every reading on every certificate needs an evidence trail back to the source page.

Citations make those answers cheap. Document intelligence captures, for every field on every extraction, the page the value came from and the bounding box where it sits on that page. The audit ledger picks up the rest.

How citations get attached

Citations come out of the parse and extract pipeline automatically. You do not configure them; they are part of every extraction the platform runs against a Schema. Each value on the structured output gets:

• A page number. The page in the source document where the value appears.
• A bounding box. Pixel coordinates (top, left, width, height) on that page.
• The original page, when the document was rotated or merged during parse.

For composite values (line items, addresses, nested objects), citations attach at the leaf level. The total of an invoice gets one citation; each line item gets its own.

Where citations show up

In the workbench

Open your Project, click the Context tab, pick Schemas, and open a Schema. In the workbench, click Try on sample in the top bar. When the result panel renders, every populated field in the Extracted fields tree carries a small chip on its right side. The chip reads p2 or p7 and points at the page in the source document.

The result panel header also surfaces a page count for the document, so you can tell at a glance whether the extraction touched every page or only a few.

In your Project's volume

When an App processes a real work item with this Schema, the platform writes a field-index.json artifact alongside the extraction result. The artifact is a leaf-level map: field_path -> {value, page, bbox} for every field in the Schema. Builders writing Runbooks can read it through the sdk.docintel runtime; analysts see it as the Inspect view on a work item's structured output.

The artifact paths look like:

• .blockparty/docintel/extracts/<doc-id>/result.json for the extraction itself.
• .blockparty/docintel/extracts/<doc-id>/field-index.json for the citations.
• .blockparty/docintel/extracts/<doc-id>/metadata.json for the run metadata.
• .blockparty/docintel/sources/<doc-id>/<file> for the source document.

These paths are off limits to direct edits (they live under the system prefix), but the platform reads them whenever a downstream surface needs to replay a citation.

In the audit ledger

Every extraction the platform runs lands as an entry in the audit ledger under the work item's group. The entry carries the Schema path, the runner version, the rule results, and a pointer to the field-index.json artifact. To trace any extracted value back to its source, open /audit, filter to the work item, and follow the entry to the artifact.

What this gives you

Three things, all audit-shaped:

• Provenance. Any extracted value can be traced to the page it came from without re-running the extraction.
• Replay. The source document is pinned alongside the extraction, so a controller can re-open the page weeks later and verify by eye.
• Forensic triage. When an extraction looks wrong, the citation tells you whether the agent misread or whether the document itself had the wrong content. Two different fixes, one citation.

What does not have citations yet

Two surfaces are still partial:

• Rule results carry a pass/fail status and a one-line message, but they do not yet carry a bounding box for the values the rule evaluated against. When a rule fails, your team has to read the underlying fields' citations to find the source. See Plain English rules for how rule results land in the result panel.
• Cross-document rules (where a rule reasons over two extractions) are not yet supported. Citations are per-document. Reconciliation across documents lives in the Runbook today.

For how to use the Schema in an App contract so analysts see citations on their work items, see App contracts and Schemas.