Open Books Developer Documentation
Turn financial files into verified JSON with Open Books. Start with a sample, then integrate through the CLI, Python, Node.js, HTTP, or MCP.
Open Books reads bank statements, payment settlements, tax documents, and Excel workpapers. For each file, it returns a complete openbooks.v1 document with verification checks and source evidence, or a typed refusal that explains why the file could not be released.
Run your first statement
Start with a two-row bank CSV. Fix a missing opening balance and trace the result back to the source.
Try the browser workspace
Use synthetic samples to learn how to run a batch, inspect its checks, and download a result.
Install Open Books locally
Set up the Python engine, install the npm packages if needed, and verify your installation.
Read the JSON contract
Learn how to branch on status, preserve exact amounts, and keep an audit trail.
Build and test an integration
Once you've run the sample, build a bank statement importer that saves each decision and computes exact debit and credit totals. Then test your integration with bundled bank, PDF, settlement, and tax fixtures. The test guide covers invalid inputs, interrupted runs, retries, and what a reviewer should be able to trace.
How a file becomes verified JSON
- Detect the layout. Open Books identifies a table or file structure it knows how to read. Two CSV files can have different layouts even when they use the same extension.
- Extract and normalize records. The engine reads values such as dates, debits, credits, and balances into a consistent schema. It records the source text and its location when available.
- Verify against the source. For a bank statement, the engine can check that opening balance plus credits minus debits equals the closing balance. At least one check must use independent evidence from the document, such as a printed closing balance.
- Return a decision. A release has
status: "ok"and includes records, assertions, and evidence. A refusal hasstatus: "refused",data: null, and a code you can act on. Read the status before importing records.
Choose an integration
| Where you work | Start here | Use it for |
|---|---|---|
| Browser | Workspace | Explore synthetic samples and review a batch by hand. |
| Terminal | CLI reference | Run local files, save JSON, and script jobs with exit codes. |
| Python 3.11+ | Python API | Call the engine inside a Python process and pass context per file. |
| Node.js 20+ | Node.js and TypeScript | Invoke the local Python engine and handle typed results. |
| Application server | Self-hosted HTTP API | Send uploads to a private engine and track per-file decisions in a stream. |
| AI agent | Model Context Protocol | Run supported operations from an MCP client and retrieve parts of the proof. |
Find a guide for your files
| Your input | What the guide covers |
|---|---|
| Bank CSV, OFX, QFX, or MT940 | Bank statements explains opening balances, date order, and signed movements. |
| Stripe or Razorpay export | Payment settlements covers fee checks, payout totals, and matching bank credits. |
| Tax export or spreadsheet | Tax documents and workpapers covers supported tables, workbook preparation, and source totals. |
| Bank PDF or image | PDFs and OCR explains text extraction, scan setup, and page evidence. |
Check the format matrix before integrating a new export. Open Books uses synthetic documents for training and evaluation. Test representative exports and the refusal path before scheduling imports. See troubleshooting when setup or processing fails.
The docs are also available as a Markdown index and a complete Markdown export.