BankConv
Convert PDF bank and credit card statements into clean transactions (JSON) or CSV, OFX, QFX, QBO and Xero CSV files with the BankConv API. Use when the user wants to read, analyse, total or import the transactions in a bank statement PDF, or needs a file for Excel, QuickBooks, Xero, Quicken, MYOB or Sage.
BankConv: bank statement PDFs to transactions and accounting files
BankConv reads the transaction tables in a PDF bank or credit card statement and returns clean transactions: ISO dates, one signed amount (money in positive, money out negative) and the running balance, with opening balances and total lines left out. It also writes CSV, OFX, QFX, QBO and Xero CSV files. It reads scanned and password-protected PDFs.
If the bankconv MCP server is connected, use its tools (convert_statement, get_transactions, download_statement, list_conversions, get_credits) instead of the steps below.
Before you start
- The API key is in
BANKCONV_API_KEY. If it is missing, ask the user to create one at https://app.bankconv.com/teams/api-keys. Never print the key. - Each PDF page uses one page of the user's BankConv account. Before converting many files, check the balance:
GET /credits. - Base URL:
https://bankconv.com/api/v1. SendAuthorization: Bearer $BANKCONV_API_KEYandAccept: application/jsonon every request.
Convert a statement
-
Upload the PDF (add
-F "password=…"only if the user gave a PDF password):bash curl -s -X POST https://bankconv.com/api/v1/conversions \ -H "Authorization: Bearer $BANKCONV_API_KEY" -H "Accept: application/json" \ -F "file=@statement.pdf"Keep
data.idfrom the response. -
Poll every 3 seconds until
data.statusiscompleted:bash curl -s https://bankconv.com/api/v1/conversions/$ID \ -H "Authorization: Bearer $BANKCONV_API_KEY" -H "Accept: application/json"Stop on
failed(the PDF couldn't be converted) orno_credits(the account needs pages; https://app.bankconv.com/plans). -
Get what the user needs:
- To analyse or answer questions:
GET /conversions/$ID/transactions. It returns the bank, account, period, currency and atransactionsarray. - To save a file:
GET /conversions/$ID/download?format=FORMAT -o FILE, where FORMAT is from the table below. For CSV useformat=csv&view=merged. TheX-BankConv-Warningsheader lists warnings as a JSON array; tell the user about them.
If either call answers
422witherror.code=not_ready, the statement details are still being read. Wait 5 seconds and retry, for up to 5 minutes. - To analyse or answer questions:
Which format
| The user wants | format | Save as |
|---|---|---|
| Excel, Google Sheets, most software | csv (with view=merged) | .csv |
| Xero, MYOB, Sage, QuickBooks Online, no column mapping | ofx | .ofx |
| Quicken | qfx | .qfx |
| QuickBooks Desktop (Web Connect) | qbo | .qbo |
| Xero's own CSV columns | xero | -xero.csv |
Errors
Errors look like {"error": {"code": "...", "message": "..."}}. Tell the user the message. Common codes: unauthenticated (bad key), insufficient_credits (not enough pages), unreadable_statement (the tables can't be read as transactions; the message names the row), gone (deleted under data retention, 24 hours by default).
Privacy
The PDF goes to BankConv over HTTPS and is deleted after 24 hours by default. Only upload files the user asked you to convert. Full API reference: https://bankconv.com/api-docs
- Downloads
- 171All time
- Security audit
- Pass
- Last updated
- 2w ago
- Current version
- v1.0.0
- License
- MIT-0
