Develop / article
Bank statement extraction API: from draft rows to approved data
An extraction response is evidence for review, not an export authorization. Use a workspace API key to inspect, correct, approve, and convert the revision you checked.
A worked example
Draft access and approval are separate
- Read revision 3
Your reviewer loads the latest saved rows. A result response is not approval.
- Another reviewer saves revision 4
Your base revision is now stale. A conflicting write must not silently replace that work.
- Refresh and review the changes
Inspect the latest state before retrying a correction or approval.
- Approve the current revision
Convert the approved revision, then map that output downstream.
Illustrative revision sequence. Use the API reference for exact requests and responses.
Give the integration its own workspace credential
The developer API uses a workspace-bound API key sent as a Bearer token. Create and hold that key on your server rather than putting it in a browser, a client-facing document, or an editorial publishing workflow. A workspace API key is not the editorial content token.
POST /api/v1/statements accepts one to ten PDFs in the files form field. Each PDF can be up to 50 MiB and 250 pages; the API upload also limits the request to 100 MiB total. Keep the returned statement IDs associated with the right workspace and source files so that later review refers to the correct statement.
Treat extracted rows as a draft
GET /api/v1/statements/{id} reports processing status. When the statement is ready for review, GET /api/v1/statements/{id}/result returns a sanitized draft with its revision, metadata, confidence, and transactions. It is not the approved export, even if the rows look complete.
Compare dates, amount signs, wrapped descriptions, balances, and page coverage with the original PDF. Source-linked review helps locate evidence for a disputed row; a confidence value cannot decide whether a client transaction is correct. Hold downstream posting or import until a person has resolved the differences.
Corrections and approval are separate decisions
PATCH /api/v1/statements/{id}/review saves supported row operations against a base revision. Corrections can include field changes, insertion, deletion, splits, and merges. Use the current revision and inspect a revision conflict instead of silently overwriting someone else’s review.
POST /api/v1/statements/{id}/approve takes the exact revision you checked. Approval is the boundary between a draft extraction and the persisted revision available for conversion; a later change must not be mistaken for the revision that was approved. The API documentation and OpenAPI specification describe the request bodies and error responses.
Choose the approved output your consumer needs
POST /api/v1/statements/convert converts approved statement IDs. JSON is returned inline; CSV, XLSX and OFX create exports with status and download URLs. Map the approved fields to your own import schema and verify the resulting file before your accounting system consumes it. Conversion is not a direct accounting-platform sync.
A request can contain up to 100 unique statement IDs, but more than one ID requires an active paid entitlement. Keep the workspace ownership boundary in mind when selecting IDs: conversion is for approved statements belonging to the authenticated workspace, not a way to combine unrelated clients’ documents without checking access.
Plan around the content lifetime
Statement sources and derived financial content expire 24 hours after presign. Review, approval, and export do not restart that deadline. Retrieve the approved output while its source remains available, and account for expiry in the integration’s handoff to a human reviewer.
If a PDF needs a password, use the statement password flow rather than putting the password in the file name or an export. For limits, request examples, and the current operation schemas, consult /api-docs and /api/openapi.json before implementing a client.
Test the output boundary with fictional data
The sample pack provides a fictional PDF and expected approved rows for a client integration. Use it to compare your downloaded export with an explicit expected record, while keeping actual extraction results and any corrections as separate observations. The downloadable sample itself does not measure extraction accuracy.
The API result endpoint returns the latest review revision. Conversion requires approval and supports JSON inline or CSV, XLSX and OFX files. On a revision conflict, fetch the latest draft and resolve the conflict instead of retrying a stale approval. Treat an expired document as unavailable; repeated polling or export requests do not extend its lifetime.
Sample files and references
- Download the fictional statement and matching exports
- Read request bodies and error responses
- Download the OpenAPI specification
- Plan the API integration lifecycle
Download the Node API walkthrough · Read the client instructions
Questions about this article
Can I use the result endpoint as final extracted data?
No. GET /api/v1/statements/{id}/result supplies a draft for inspection. Save corrections, approve the exact reviewed revision, and use the convert endpoint for approved output.
Does conversion return a downloadable file for JSON?
No. Approved JSON is returned inline. CSV, XLSX and OFX conversion create exports with a status URL and a download URL.
Can I convert several statements with one API request?
Yes, up to 100 unique IDs, provided the statements belong to the authenticated workspace and are approved. More than one ID requires an active paid entitlement.