API reference

BankFlow v1 API

Parse bank statements programmatically. POST a PDF, get structured JSON back. The same engine that powers the app, available over a simple REST API. API access is available on all paid plans.

Authentication

Generate a personal access token (prefixed ktrx_) from the API settings in the app. Pass it as a bearer token on every request — including the OpenAPI endpoint.

http

Authorization: Bearer ktrx_your_api_key_here

Quickstart

Send a PDF to /api/v1/parse and receive the parsed bank and transactions synchronously.

curl

curl -X POST https://api.bankflow.app/api/v1/parse \
  -H "Authorization: Bearer ktrx_your_api_key_here" \
  -H "Content-Type: application/pdf" \
  --data-binary @statement.pdf

javascript (Node.js)

const fs = require('fs');

const pdf = fs.readFileSync('statement.pdf');

const res = await fetch('https://api.bankflow.app/api/v1/parse', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer ktrx_your_api_key_here',
    'Content-Type': 'application/pdf',
  },
  body: pdf,
});

const data = await res.json();
console.log(data.bank_id);
console.log(data.transactions);

python

import requests

with open('statement.pdf', 'rb') as f:
    pdf_bytes = f.read()

response = requests.post(
    'https://api.bankflow.app/api/v1/parse',
    headers={
        'Authorization': 'Bearer ktrx_your_api_key_here',
        'Content-Type': 'application/pdf',
    },
    data=pdf_bytes,
)

data = response.json()
print(data['bank_id'])
for txn in data['transactions']:
    print(txn['date'], txn['desc'], txn['debit'], txn['credit'])

Example response

json

{
  "bank_id": "BOA Bank",
  "transactions": [
    {
      "date": "2024-01-03",
      "desc": "UPI/SWIGGY/Food Order",
      "debit": 450.00,
      "credit": null,
      "balance": 24550.00
    },
    {
      "date": "2024-01-05",
      "desc": "SALARY CREDIT",
      "debit": null,
      "credit": 85000.00,
      "balance": 109550.00
    }
  ],
  "validation": {
    "passed": true,
    "issues": []
  }
}

Statements

Upload, inspect, delete, analyze, and export parsed statements.

GET/api/v1/statementsList statements

Returns paginated statements with processing status, bank, source, and transaction count.

Query

page, limit

status=processing|completed|failed

search, from, to

Response

{ data: Statement[], pagination }

POST/api/v1/statementsUpload and persist a statement

Accepts multipart form-data with field file, or raw PDF bytes, parses synchronously, and stores the statement plus transactions.

Body

multipart/form-data → file

application/pdf raw body

Limits

Max 50MB

Optional: X-PDF-Password header

GET/api/v1/statements/:idGet statement details

Fetches one statement with processing status, balances, period, and metadata.

Path

:id = statement id

Response

{ data: StatementDetail }

DELETE/api/v1/statements/:idDelete a statement

Deletes the statement and all associated transactions.

Path

:id = statement id

Response

{ success: true }

GET/api/v1/statements/:id/transactionsList statement transactions

Returns paginated transactions for a single statement with category, type, search, and date filters.

Query

page, limit

category, type

search, from, to

Response

{ data: Transaction[], pagination }

GET/api/v1/statements/:id/insightsGet financial insights

Computes income, expenses, savings, top categories, recurring payments, salary detection, and monthly cashflow.

Path

:id = statement id

Response

{ data: Insights }

GET/api/v1/statements/:id/exportExport a statement

Exports one statement as JSON, CSV, or XLSX with optional filters.

Query

format=json|csv|xlsx

category, type

search, from, to

Response

JSON envelope or file download

Transactions

Manually correct transaction metadata and feed the learning system.

PATCH/api/v1/transactions/:idUpdate transaction metadata

Updates category, notes, and tags for a stored transaction.

Body

{ category?, notes?, tags?: string[] }

Response

{ success: true }

Webhooks

GET/api/v1/webhooksList registered webhooks

Returns every webhook endpoint registered for your API key owner.

Response

{ data: Webhook[] }

Events

statement.completed

statement.failed

statement.deleted

transaction.updated

POST/api/v1/webhooksRegister a webhook

Creates a webhook endpoint and returns the generated signing secret once.

Body

{ url: string, events: string[] }

Response

{ data: { id, url, events, secret } }

DELETE/api/v1/webhooks/:idDelete a webhook

Removes a registered webhook endpoint.

Path

:id = webhook id

Response

{ success: true }

OpenAPI

Machine-readable API specification for tooling and Swagger-style docs.

GET/api/v1/openapi.jsonRaw OpenAPI 3.0 spec

Returns the complete BankFlow v1 OpenAPI document as JSON.

Use cases

Swagger UI

SDK generation

Schema inspection

Response

OpenAPI 3.0.3 JSON document

Need the machine-readable spec?

The full OpenAPI 3.0 document is available at https://api.bankflow.app/api/v1/openapi.json for Swagger UI and SDK generation.