JSON output contract
Integrate the openbooks.v1 release and refusal contract with exact decimal money, source evidence and verification assertions.
Every completed document decision uses the openbooks.v1 JSON schema. The CLI, Python, Node.js, and HTTP API expose the same underlying document. Some entry points wrap it in a result or event, so unwrap it before applying the contract below.
Read the envelope first
- Check
schema_versionagainst the version your integration supports. - For
status: "ok", read the released records underdataand retain their assertions and source evidence. - For
status: "refused", readerror.codeanderror.message. The document hasdata: null. - Handle missing decisions, such as a timeout or interrupted stream, at the job level. See refusal and execution handling.
Released documents
| Field | Contents |
|---|---|
status | "ok" |
file | Input name and SHA-256, detected format, layout version and extraction method. A model-checked release also identifies the weights and calibration by SHA-256. |
data | accounts, parties, batches, transactions and claims. Collections can be empty and fields vary with the layout. |
evidence | Source locations and raw text indexed by record and field. |
assertions | Statement, settlement or layout-specific checks. All must pass with at least one independent check. |
This transaction is from the sample terminal.
{
"id": "txn-00001",
"batch_id": "batch-1",
"account_id": "acct-1",
"date": "2026-01-02",
"direction": "debit",
"amount": { "amount": "100.00", "currency": "INR" },
"balance_after": { "amount": "900.00", "currency": "INR" },
"description": "Sample payment",
"reference": null
}Retain money as decimal strings, and use a decimal library for arithmetic. Carry the currency alongside the amount. Date fields are ISO calendar dates where the layout supplies a date. Scope record IDs to their source document when combining files.
Evidence and independent checks
Use the record ID and field name to find the source. In the quickstart, evidence["txn-00001.amount"] gives the first transaction's amount as it appeared on row 2 of the CSV.
{
"page": null,
"bbox": null,
"row": 2,
"raw_text": "100.00",
"method": "parser"
}page, bbox, and row describe where to look and can be null when a location is unavailable or inapplicable. raw_text preserves the source reading or records that a value was supplied by the caller. method records how the field was extracted.
Each assertion reports id, rule, expected, computed, passed, and independent. The quickstart's closing-balance assertion compares an expected "950.00 INR" from the source against the same amount computed from the opening balance and transactions. It passes and is independent because the expected closing amount comes from the CSV.
Refused documents
{
"schema_version": "openbooks.v1",
"status": "refused",
"data": null,
"error": {
"code": "PARSE_ERROR",
"message": "statement has no stated opening balance; supply --opening",
"file_sha256": "4cbb7e3f45dc4860ba6c14e51b32a2667fbb526b4f6f78e7861bc3d6b4f1f997"
}
}Read error.code for programmatic handling and error.message during review. The refusal hash is error.file_sha256. In a release, it is file.sha256. Both identify the exact input bytes. Store processing parameters and versions when the same bytes may be run with different settings.
Validate documents at the integration boundary
Use the release schema or refusal schema according to the document status. Both are included in the Python package and mirrored by the Node.js validation helpers. When retaining normalized records, store the original decision with enough context to find its assertions and evidence later. See the Python API for a validation example.
MCP for AI agents
Download and install the Open Books Model Context Protocol server to verify financial files with an AI agent and inspect the evidence in one batched call.
Refusals and execution errors
Find all six refusal codes, diagnose failed documents, and design retry and review behavior for reliable financial imports.