API

The same API the web application uses, available to paid plans with API keys. Upload a PDF, start a conversion, poll until it completes, download the exports or read the transactions as JSON.

Authentication

Create an API key in the application under API keys. Keys are shown once, carry scopes (conversions:read, conversions:write, usage:read) and can be revoked at any time. Send the key as a bearer token.

Header on every request

Authorization: Bearer lk_live_…

All requests and responses are JSON except file uploads and downloads. Money values are decimal strings ("1234.56"), dates are YYYY-MM-DD, and ids are public prefixed ids (upl_, conv_, exp_).

Quick start: one request per statement

The /statements endpoint uploads and converts in a single multipart request. Poll the returned id until the status is COMPLETED or NEEDS_REVIEW, then download.

Upload and convert

curl -X POST https://app.bankingconverter.com/api/v1/statements \
  -H "Authorization: Bearer lk_live_…" \
  -F "[email protected]" \
  -F "formats[]=csv" -F "formats[]=json"

# 201
{ "id": "conv_8f3…", "status": "QUEUED" }

Poll, then download

curl https://app.bankingconverter.com/api/v1/conversions/conv_8f3… \
  -H "Authorization: Bearer lk_live_…"

# 200 (abbreviated)
{ "conversion": { "id": "conv_8f3…", "status": "COMPLETED", "confidence": "0.9920", "reconciled": true,
    "transaction_count": 60, "pages_charged": 12,
    "exports": [ { "id": "exp_1a…", "format": "csv", "profile": "accounting", "filename": "august.csv" } ] },
  "validation": { "reconciled": true, "confidence": 0.992, "issues": [] },
  "accounts": [ { "institution": "Northgate Bank", "currency": "USD", "opening_balance": "8420.00", "closing_balance": "9300.63" } ] }

curl -L "https://app.bankingconverter.com/api/v1/conversions/conv_8f3…/download?export=exp_1a…" \
  -H "Authorization: Bearer lk_live_…" -o august.csv

The full flow

For large files or when you want to inspect the document before spending page credits, use the three-step upload flow.

Step	Request	Result
1. Create upload	`POST /api/v1/uploads` with `{ filename, size_bytes, content_type }`	`upload.id`, a signed `upload_url` and the headers to send
2. Send the bytes	`PUT upload_url` with the PDF body and the returned headers	Object stored under a random key in private storage
3. Complete	`POST /api/v1/uploads/{id}/complete` (optional `{ password }`)	`page_count`, `encrypted`, `needs_password`, `doc_class` (TEXT_BASED, IMAGE_BASED, HYBRID)
4. Convert	`POST /api/v1/conversions` with `{ upload_id, formats, options }`	`conversion` in status `QUEUED`; page credits are charged once per conversion
5. Poll	`GET /api/v1/conversions/{id}`	Status progresses through PROCESSING, OCR, EXTRACTING, NORMALIZING, VALIDATING, EXPORTING
6. Read or download	`GET …/transactions`, `GET …/download?format=csv`, `?all=1` for a ZIP	Transactions with `source_page`, `source_bbox`, `confidence` and `flags`; downloads redirect to short-lived signed URLs

Conversion options

{
  "upload_id": "upl_…",
  "formats": ["csv", "xlsx", "ofx", "qbo", "json"],
  "options": {
    "export_common": { "date_format": "YYYY-MM-DD", "delimiter": "," },
    "export": { "csv": { "profile": "accounting" } },
    "financial_institution": { "org": "…", "fid": "…", "intu_bid": "…", "bank_id": "…" }
  }
}

financial_institution is required for QBO and is never inferred. Editing endpoints (PATCH …/transactions with update, insert, delete, merge and split operations) regenerate exports; DELETE /api/v1/conversions/{id} purges the original, data and exports immediately.

Statuses and error codes

Conversion status	Meaning
`QUEUED` … `EXPORTING`	In progress; keep polling. Typical statements finish in seconds; OCR takes longer.
`COMPLETED`	Reconciled with no low-confidence rows. Exports are ready.
`NEEDS_REVIEW`	Finished, but the statement did not fully reconcile or has flagged rows. Exports exist; inspect `validation.issues`.
`NEEDS_PASSWORD`	The PDF is encrypted. Send the password to `POST …/password` to requeue.
`FAILED`	See `error.code`. `POST …/retry` requeues without a second charge.

Error code	When
`PDF_CORRUPT`	The file is not a readable PDF
`PASSWORD_REQUIRED` / `PASSWORD_INCORRECT`	Encrypted document
`OCR_FAILED`	Image pages could not be recognised
`NO_TRANSACTION_TABLE`	No transaction table was found
`LOW_CONFIDENCE` / `BALANCE_MISMATCH`	Extraction completed but did not pass validation thresholds
`FILE_TOO_LARGE` / `TOO_MANY_PAGES`	Beyond the plan or system limits
`PROCESSING_TIMEOUT` / `INTERNAL_ERROR`	Retry; contact support with the conversion id if it repeats
`INSUFFICIENT_CREDITS` (402), `FORMAT_NOT_IN_PLAN` (403), `FILE_TOO_LARGE_FOR_PLAN` (403)	Plan gating at conversion time
`PASSWORD_PROTECTED_NOT_IN_PLAN` (403)	The plan does not include encrypted PDFs

Error envelope

{ "error": { "code": "PASSWORD_REQUIRED", "message": "This PDF is password protected." } }

Rate limits and quotas

Page credits: each conversion charges the statement's page count once, against your plan's monthly allowance plus any purchased packs. GET /api/v1/usage returns the current period, used and remaining pages.
Request rate limits are applied per API key and per IP; a limited request returns 429 with a Retry-After header.
File limits (maximum size and pages per file), the export formats the plan may produce and whether it accepts password-protected PDFs all depend on the plan and are returned by GET /api/v1/usage as plan.max_file_mb, plan.max_pages_per_file, plan.formats and plan.password_protected.
Originals are deleted 24 hours after processing; exports and extracted transactions 7 days after conversion. Download what you need within that window or fetch the transactions as JSON. When the organisation enables Purge on download, everything is removed 10 minutes after the first download, including downloads made with an API key.

Reference

The complete contract, including the transaction editing operations, batch merge, feedback and API key endpoints, is documented in the repository's API reference. API access is included in paid plans; see pricing. Questions: [email protected].