StatementPro.ai API Documentation
Convert bank statements to JSON or CSV from your own software. Upload a file, start a conversion, then poll for the result. A signed webhook may also notify you, but delivery is best effort.
Reference status. This page describes the API as it behaves today. There is no machine-readable OpenAPI specification; this page is the reference. Values marked subject to change can change without a new version of this page, so read them from the response headers in your code rather than hard-coding them.
Contents
- How a conversion works
- Get an API key
- Use from an AI assistant (MCP)
- Authentication
- 1. Request an upload URL
- 2. Upload the file
- 3. Start the conversion
- 4. Check the job
- 5. Download the result
- Webhooks
- List your conversions
- Your account and credits
- Credits
- Errors
- Rate limits
- Full example: Python
- Full example: Node.js
- Start using the API
How a conversion works
API requests use the base URL https://statementpro.ai/v1. Upload the file to the separate uploadUrl returned by POST /v1/uploads; do not send your API key to that URL. Converting one statement takes these steps:
- Request an upload URL with
POST /v1/uploads. - Upload the file with an HTTP
PUTto the URL you got back. - Start the conversion with
POST /v1/convert. Credits are charged at this step. - Wait for the job to finish: poll
GET /v1/jobs/{id}. Ajob.completedorjob.failedwebhook may notify you; poll for jobs without an event. - Download the result as JSON or CSV with
GET /v1/jobs/{id}/result.
Each job converts one file: a PDF, PNG or JPEG of up to 25 MB. To convert several statements, run one job per file.
Get an API key
Any account that has bought a credit pack, of any size, can create an API key. API access does not expire.
- Log in and open Settings. Find the API access card.
- If your account has not bought a credit pack yet, the card links to Credits & Billing. Buy any pack, then come back to Settings.
- Click Create API key. The full key is shown once: copy it, store it somewhere safe, then click I’ve saved it. Afterwards Settings shows only the key’s prefix, with its created and last-used dates.
Live keys start with sp_live_. Each account has one active key. Regenerate replaces it and the old key stops working immediately; Revoke turns it off. Keep the key on your server and out of browser or mobile code.
Your key keeps working after your purchased credits run out or expire. GET requests still work, and POST /v1/convert returns 402 INSUFFICIENT_CREDITS until you buy another pack.
Use the API from an AI assistant (MCP)
If you’d rather not write code, the StatementPro.ai MCP server lets an AI assistant call this API for you. It offers six tools: get_account, convert_document (quote only, never charges), confirm_conversion (converts and spends credits), get_job, list_conversions and get_result.
- Claude and ChatGPT: add a connector with the URL
https://statementpro.ai/v1/mcp. You sign in to StatementPro.ai and approve the connection; no API key is needed. Connected assistants always quote before converting. - Claude Code, Cursor, VS Code and other local MCP clients: install the npm package
@statementpro/mcpand setSTATEMENTPRO_API_KEYto your key. It needs Node.js 22 or later.
Conversions the npm package makes with your API key are ordinary API jobs, so they appear in your conversions list. Setup steps and example prompts are on the MCP server page.
Authentication
Send the key as a Bearer token in the Authorization header of every /v1 request:
Authorization: Bearer sp_live_your_key_here
A missing, malformed or revoked key gets 401 UNAUTHORIZED. A valid key on an account that has never bought a credit pack gets 403 FORBIDDEN. The examples below read the key from an environment variable:
export STATEMENTPRO_API_KEY="sp_live_your_key_here"
curl https://statementpro.ai/v1/me \
-H "Authorization: Bearer $STATEMENTPRO_API_KEY"
Do not send a request body on GET requests. They are rejected before they reach the API, with a 403 response that does not use the JSON error format described under Errors.
1. Request an upload URL
POST /v1/uploads with the file name and its content type. contentType must be application/pdf, image/png or image/jpeg.
curl -X POST https://statementpro.ai/v1/uploads \
-H "Authorization: Bearer $STATEMENTPRO_API_KEY" \
-H "Content-Type: application/json" \
-d '{"fileName": "march-2026.pdf", "contentType": "application/pdf"}'
Response 201 Created:
{
"uploadId": "3f6c2a8e-5b1d-4c7a-9e2f-8a4b6d0c1e93",
"uploadUrl": "https://...",
"uploadHeaders": { "Content-Type": "application/pdf" },
"expiresAt": "2026-10-20T15:15:00Z"
}
The uploadUrl is valid for 15 minutes. Keep the uploadId: you need it to start the conversion.
2. Upload the file
PUT the file’s raw bytes to uploadUrl, sending every header in uploadHeaders. Do not send your API key to this URL.
Set UPLOAD_URL to the uploadUrl value from step 1 (paste the full URL, in quotes), then send the file:
UPLOAD_URL="paste the uploadUrl from step 1 here"
curl -X PUT "$UPLOAD_URL" \
-H "Content-Type: application/pdf" \
--data-binary @march-2026.pdf
A 200 response means the file is stored. Size and content are checked in the next step: the file must be 25 MB or smaller, not empty, and its content must match the type you declared.
3. Start the conversion
POST /v1/convert with the uploadId. An Idempotency-Key header is required: any unique string of 1 to 255 characters, such as a UUID.
curl -X POST https://statementpro.ai/v1/convert \
-H "Authorization: Bearer $STATEMENTPRO_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: 0b9d4d52-6a0e-4b38-9a43-5c1f3e2d7a10" \
-d '{"uploadId": "3f6c2a8e-5b1d-4c7a-9e2f-8a4b6d0c1e93"}'
Response 202 Accepted. The job’s id is the same value as the uploadId:
{
"id": "3f6c2a8e-5b1d-4c7a-9e2f-8a4b6d0c1e93",
"status": "queued",
"pageCount": 4,
"creditsCharged": 1,
"createdAt": "2026-10-20T15:00:12Z"
}
The pages are counted and the credits are charged before this response is sent. See Credits.
Optional: confirm the cost first
To show the cost before charging, for example so a person can approve it, get a quote after uploading the file by adding "quote": true. A quote never charges anything and needs no Idempotency-Key:
curl -X POST https://statementpro.ai/v1/convert \
-H "Authorization: Bearer $STATEMENTPRO_API_KEY" \
-H "Content-Type: application/json" \
-d '{"uploadId": "3f6c2a8e-5b1d-4c7a-9e2f-8a4b6d0c1e93", "quote": true}'
Response 200 OK:
{
"quoteId": "9a1e7c4b-2d3f-4e8a-b6c5-0f1d2e3a4b5c",
"uploadId": "3f6c2a8e-5b1d-4c7a-9e2f-8a4b6d0c1e93",
"pageCount": 23,
"credits": 3,
"paidCreditsRemaining": 40,
"sufficient": true,
"expiresAt": "2026-10-20T15:10:00Z"
}
Then start the conversion with the quoteId as well: {"uploadId": "...", "quoteId": "..."}. It is charged only if the quote is the latest one for that upload, has not expired (quotes last 10 minutes), and the file still costs the quoted amount. Otherwise you get 409 QUOTE_INVALID and nothing is charged: get a new quote and try again. sufficient is false when your balance is below the quoted credits. Without a quoteId, POST /v1/convert works exactly as described above.
Retrying safely
If a request times out or the connection drops, send it again with the same Idempotency-Key. You will not be charged twice:
- If the first request was accepted, you get the original
202response back, with anIdempotent-Replayed: trueheader. - If the first request returned
502, you get that502back. Its credits are returned automatically, and the upload cannot be converted again: request a new upload URL, upload the file again and start a new conversion with a newIdempotency-Key. - If the first request is still running, you get
409 CONFLICT. Wait a moment and retry. - A
400,402or409response is returned before anything is charged, so you can fix the problem and retry with the same key. - Reusing a key with a different
uploadIdreturns409 CONFLICT. - Each upload converts once. Starting it again with a new key returns
409“This upload has already been converted.”
4. Check the job
GET /v1/jobs/{id} returns the job’s current state.
curl https://statementpro.ai/v1/jobs/3f6c2a8e-5b1d-4c7a-9e2f-8a4b6d0c1e93 \
-H "Authorization: Bearer $STATEMENTPRO_API_KEY"
{
"id": "3f6c2a8e-5b1d-4c7a-9e2f-8a4b6d0c1e93",
"status": "completed",
"fileName": "march-2026.pdf",
"pageCount": 4,
"creditsCharged": 1,
"creditReturned": false,
"createdAt": "2026-10-20T15:00:12Z",
"completedAt": "2026-10-20T15:01:03Z",
"error": null
}
status | Meaning |
|---|---|
queued | Accepted and waiting to start. |
processing | The statement is being converted. |
completed | The result is ready to download. completedAt is set. |
failed | The conversion did not finish. error says why, and creditReturned is true once the job’s credits are back in your balance. |
If you poll, wait a few seconds between requests. Each poll counts toward your rate limit. Webhooks reduce routine polling. A webhook delivery can fail, so still check now and then for jobs you have not heard about.
5. Download the result
GET /v1/jobs/{id}/result?format=json or ?format=csv. JSON is the default. Until the job is completed, this returns 409 CONFLICT.
curl "https://statementpro.ai/v1/jobs/3f6c2a8e-5b1d-4c7a-9e2f-8a4b6d0c1e93/result?format=json" \
-H "Authorization: Bearer $STATEMENTPRO_API_KEY"
JSON
{
"schemaVersion": 1,
"id": "3f6c2a8e-5b1d-4c7a-9e2f-8a4b6d0c1e93",
"metadata": {
"fileName": "march-2026.pdf",
"pageCount": 4,
"bank": "Example Bank",
"statementPeriod": "March 1, 2026 - March 31, 2026",
"statementType": "bank"
},
"accounts": [
{
"accountNumberLast4": "4321",
"balanceSummary": {
"openingBalance": "2500.00",
"closingBalance": "2412.15",
"totalCredits": "1200.00",
"totalDebits": "1287.85"
},
"transactions": [
{
"date": "2026-03-02",
"description": "Payroll deposit",
"amount": "1200.00",
"balance": "3700.00",
"type": "credit"
},
{
"date": "2026-03-04",
"description": "Office rent",
"amount": "-1287.85",
"balance": "2412.15",
"type": "debit"
}
]
}
]
}
- A statement can hold more than one account;
accountsis an array with one entry per account found.accountNumberLast4is the last four digits of that account’s number; it is not a unique key, as two accounts can end in the same four digits. - Amounts are decimal strings with two places, so no precision is lost. Debits are negative and credits positive;
typerepeats the sign asdebitorcredit. - Dates are ISO 8601 (
YYYY-MM-DD). - Some values are worked out rather than read directly.
openingBalancecan be derived from the first running balance and the transactions before it,totalCreditsandtotalDebitsare added up from the transactions, and a transaction date printed without a year takes its year from the statement period. A description that cannot be read is an empty string. Check totals against the statement before you rely on them. schemaVersionis currently1. This page is the reference for the result shape.statementTypetells you what kind of statement was read. This page documents thebanklayout, so checkstatementTypebefore you parse a result.
CSV
One row per transaction, with this header row:
Bank Name,Statement Period,Account Number,Date,Description,Debits,Credits,Balance
The CSV response has the content type text/csv; charset=utf-8.
Webhooks
As well as polling, you can have StatementPro.ai send an HTTPS POST to your server when a job finishes. Delivery is best effort, so keep polling for jobs you have not heard about. Set it up in Settings, on the API access card:
- Enter your endpoint’s HTTPS URL and click Save.
- Copy the signing secret (it starts with
whsec_). Like the API key, it is shown once. Regenerate signing secret replaces it, and new deliveries are signed with the new secret straight away.
Each account has one webhook URL. Remove webhook stops deliveries and cancels pending ones; you can still poll.
Events
job.completed:
{
"eventId": "9a1e7c4b-2f3d-4e5a-8b6c-7d8e9f0a1b2c",
"event": "job.completed",
"createdAt": "2026-10-20T15:01:04Z",
"jobId": "3f6c2a8e-5b1d-4c7a-9e2f-8a4b6d0c1e93",
"status": "completed",
"pageCount": 4,
"creditsCharged": 1,
"completedAt": "2026-10-20T15:01:03Z"
}
job.failed:
{
"eventId": "5c2d8e1f-3a4b-4c6d-9e7f-0a1b2c3d4e5f",
"event": "job.failed",
"createdAt": "2026-10-20T15:03:40Z",
"jobId": "3f6c2a8e-5b1d-4c7a-9e2f-8a4b6d0c1e93",
"failureClass": "processing_failed",
"creditReturned": true,
"failedAt": "2026-10-20T15:03:39Z"
}
failureClass is submission_failed, timeout or processing_failed. A timeout can also mean the statement was read but no transactions were found in it; its credits are returned the same way. creditReturned reflects the moment the event was sent; if the refund completes later, no second event is sent, and GET /v1/jobs/{id} shows the final value.
The event tells you the job is finished; download the data with GET /v1/jobs/{id}/result.
Headers
| Header | Value |
|---|---|
X-StatementPro-Signature | t=<unix seconds>,v1=<hex HMAC-SHA256> |
X-StatementPro-Event | job.completed or job.failed |
X-StatementPro-Event-Id | Same as eventId in the body |
User-Agent | StatementPro-Webhooks/1 |
Verify the signature
Compute an HMAC-SHA256 of the string <t>.<raw request body>, using your whole signing secret (including the whsec_ prefix) as the key. Compare the hex digest with v1 in constant time. Reject the request if they differ, or if t is more than a few minutes old. Use the raw body exactly as received: parsing and re-serializing the JSON first changes it and breaks the signature.
Python:
import hashlib
import hmac
import time
def verify_statementpro_signature(header, raw_body, secret, tolerance_seconds=300):
"""header: X-StatementPro-Signature value. raw_body: request body as bytes."""
parts = dict(p.split("=", 1) for p in (header or "").split(",") if "=" in p)
t, v1 = parts.get("t", ""), parts.get("v1", "")
if not t.isdigit() or not v1:
return False
if abs(time.time() - int(t)) > tolerance_seconds:
return False
expected = hmac.new(secret.encode(), t.encode() + b"." + raw_body, hashlib.sha256).hexdigest()
return hmac.compare_digest(expected, v1)
Node.js:
import crypto from 'node:crypto'
// header: X-StatementPro-Signature value. rawBody: request body as a Buffer or string.
export function verifyStatementProSignature(header, rawBody, secret, toleranceSeconds = 300) {
const parts = Object.fromEntries((header ?? '').split(',').map(p => p.split('=', 2)))
if (!parts.t || !parts.v1) return false
if (Math.abs(Date.now() / 1000 - Number(parts.t)) > toleranceSeconds) return false
const expected = crypto.createHmac('sha256', secret).update(`${parts.t}.`).update(rawBody).digest('hex')
return expected.length === parts.v1.length &&
crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(parts.v1))
}
Delivery and retries
- Respond with any
2xxstatus within 5 seconds. Do slow work after you respond. - Redirects are not followed. The URL must use HTTPS and resolve to a public address.
- Webhook delivery is best effort. A delivery that times out, cannot connect, or receives a
5xx,408or429response may be retried, up to 3 attempts in total. Retry timing is not guaranteed. Any other response ends delivery for that event. PollGET /v1/jobs/{id}orGET /v1/conversionsfor jobs you have not heard about. - The same event can arrive more than once. Use
eventIdto ignore duplicates. - Events are not guaranteed to arrive in order, and a delivery can fail for good. If you depend on webhooks, also check
GET /v1/jobs/{id}orGET /v1/conversionsfor jobs you have not heard about.
List your conversions
GET /v1/conversions returns your API jobs, newest first, as job objects (the same shape as GET /v1/jobs/{id}).
| Query parameter | Description |
|---|---|
status | Optional. queued, processing, completed or failed. |
created_ | Optional. ISO 8601 timestamp, for example 2026-10-01T00:00:00Z. |
limit | Optional. 1 to 100; default 25. |
cursor | Optional. The nextCursor from the previous page. |
curl "https://statementpro.ai/v1/conversions?status=completed&limit=50" \
-H "Authorization: Bearer $STATEMENTPRO_API_KEY"
{
"data": [
{
"id": "3f6c2a8e-5b1d-4c7a-9e2f-8a4b6d0c1e93",
"status": "completed",
"fileName": "march-2026.pdf",
"pageCount": 4,
"creditsCharged": 1,
"creditReturned": false,
"createdAt": "2026-10-20T15:00:12Z",
"completedAt": "2026-10-20T15:01:03Z",
"error": null
}
],
"nextCursor": null
}
When nextCursor is null, there are no more pages.
Your account and credits
GET /v1/me checks your key and returns your credit balance.
{
"userId": "b7e1c2d3-4f5a-4b6c-8d9e-0f1a2b3c4d5e",
"email": "you@example.com",
"paidCreditsRemaining": 48,
"freeCreditsRemaining": 0,
"apiKeyPrefix": "sp_live_AbCd"
}
Credits
- An API conversion costs 1 credit per 10 pages, rounded up, the same rate as the web app. A 4-page statement costs 1 credit; a 23-page statement costs 3. An image counts as one page.
- API conversions use purchased credits only. Free credits are not used by the API;
freeCreditsRemaininginGET /v1/meapplies to the web app. - If your balance is too low,
POST /v1/convertreturns402 INSUFFICIENT_CREDITSwith the page count and the credits needed. Nothing is charged. - If a conversion fails, its credits are returned to your balance automatically. The job shows
creditReturned: trueonce they are back. - Purchased credits are valid for 12 months and the oldest are used first. When none are left, your key keeps working for
GETrequests, and new conversions return402until you buy another pack.
Buy credit packs on Credits & Billing. Pack sizes and prices are on the pricing page.
Errors
Errors return a JSON body with a stable code and a readable message:
{ "error": { "code": "INSUFFICIENT_CREDITS", "message": "This document has 23 pages and needs 3 paid credits; 1 available." } }
| Status | code | When |
|---|---|---|
| 400 | VALIDATION_ | A missing or invalid field or header; a file that is empty, over 25 MB, unreadable, or not the type you declared; or /v1/convert called before the file was uploaded. |
| 401 | UNAUTHORIZED | Missing, malformed or revoked API key. |
| 402 | INSUFFICIENT_ | Not enough purchased credits for this document. |
| 403 | FORBIDDEN | The account has not bought a credit pack. |
| 404 | NOT_ | No job with this id on your account, or its result is no longer available. |
| 409 | CONFLICT | The result was requested before the job completed; the upload was already converted; or an Idempotency-Key clash (see Retrying safely). |
| 409 | QUOTE_ | The quoteId sent to /v1/convert is not the upload’s latest quote, has expired, or no longer matches the file. Nothing is charged; get a new quote (see Optional: confirm the cost first). |
| 429 | RATE_ | Too many requests. Wait for the number of seconds in Retry-After. |
| 500, 502 | INTERNAL_ | Something went wrong on our side. Retry with backoff. A 502 from /v1/convert means the document could not be submitted. Its credits are returned automatically; if that cannot happen straight away, it is retried later. Retrying with the same Idempotency-Key returns the same 502, so upload the file again (see Retrying safely). |
Responses from the API include an X-Request-Id header. Two kinds of response do not: the file upload to uploadUrl, and requests rejected before they reach the API, such as a request to a path that does not exist, which get a 403 without the JSON error body. Include the id when you contact support@statementpro.ai about a request.
Rate limits
Each API key can make 60 requests per minute (subject to change). Uploads to uploadUrl do not count. Authenticated /v1 responses, including 429, carry the current values; 401 and 403 responses do not:
| Header | Meaning |
|---|---|
X-RateLimit-Limit | Requests allowed in the current window. |
X-RateLimit-Remaining | Requests left in the current window. |
X-RateLimit-Reset | Unix time when the window resets. |
Retry-After | On a 429 only: seconds to wait before retrying. |
Full example: Python
Converts one PDF and prints its transactions. Needs Python 3.8+ and requests (pip install requests).
import os
import time
import uuid
import requests
API = "https://statementpro.ai/v1"
AUTH = {"Authorization": f"Bearer {os.environ['STATEMENTPRO_API_KEY']}"}
def check(resp):
"""Raise with the API's error code, message and request id."""
if resp.status_code >= 400:
try:
err = resp.json()["error"]
except (ValueError, KeyError):
err = {"code": "HTTP_ERROR", "message": resp.text[:200]}
raise RuntimeError(f"{resp.status_code} {err['code']}: {err['message']} "
f"(X-Request-Id {resp.headers.get('X-Request-Id')})")
return resp
path = "march-2026.pdf"
# 1. Request an upload URL.
upload = check(requests.post(f"{API}/uploads", headers=AUTH, json={
"fileName": os.path.basename(path),
"contentType": "application/pdf",
})).json()
# 2. Upload the file with the headers we were given.
with open(path, "rb") as f:
requests.put(upload["uploadUrl"], headers=upload["uploadHeaders"], data=f).raise_for_status()
# 3. Start the conversion. Reuse this key if you retry the same request.
idempotency_key = str(uuid.uuid4())
job = check(requests.post(f"{API}/convert",
headers={**AUTH, "Idempotency-Key": idempotency_key},
json={"uploadId": upload["uploadId"]})).json()
print(f"Job {job['id']}: {job['pageCount']} pages, {job['creditsCharged']} credits")
# 4. Poll until the job finishes.
while True:
status = check(requests.get(f"{API}/jobs/{job['id']}", headers=AUTH)).json()
if status["status"] in ("completed", "failed"):
break
time.sleep(5)
if status["status"] == "failed":
raise RuntimeError(f"{status['error']} (credits returned: {status['creditReturned']})")
# 5. Download the result.
result = check(requests.get(f"{API}/jobs/{job['id']}/result",
headers=AUTH, params={"format": "json"})).json()
for account in result["accounts"]:
for tx in account["transactions"]:
print(tx["date"], tx["amount"], tx["description"])
Full example: Node.js
The same flow with the built-in fetch, saving the CSV. Needs Node.js 18+; save as convert.mjs and run node convert.mjs.
import { readFile, writeFile } from 'node:fs/promises'
import { basename } from 'node:path'
import { randomUUID } from 'node:crypto'
const API = 'https://statementpro.ai/v1'
const AUTH = { Authorization: `Bearer ${process.env.STATEMENTPRO_API_KEY}` }
// Calls the API and throws with its error code, message and request id.
async function api(path, { headers, ...options } = {}) {
const res = await fetch(`${API}${path}`, { ...options, headers: { ...AUTH, ...headers } })
if (!res.ok) {
const { error } = await res.json().catch(() => ({ error: { code: 'HTTP_ERROR', message: res.statusText } }))
throw new Error(`${res.status} ${error.code}: ${error.message} (X-Request-Id ${res.headers.get('x-request-id')})`)
}
return res
}
const sleep = ms => new Promise(resolve => setTimeout(resolve, ms))
const file = 'march-2026.pdf'
// 1. Request an upload URL.
const upload = await (await api('/uploads', {
method: 'POST',
headers: { 'Content-Type': 'application/json' },
body: JSON.stringify({ fileName: basename(file), contentType: 'application/pdf' }),
})).json()
// 2. Upload the file with the headers we were given.
const put = await fetch(upload.uploadUrl, { method: 'PUT', headers: upload.uploadHeaders, body: await readFile(file) })
if (!put.ok) throw new Error(`Upload failed: ${put.status}`)
// 3. Start the conversion. Reuse this key if you retry the same request.
const idempotencyKey = randomUUID()
const job = await (await api('/convert', {
method: 'POST',
headers: { 'Content-Type': 'application/json', 'Idempotency-Key': idempotencyKey },
body: JSON.stringify({ uploadId: upload.uploadId }),
})).json()
console.log(`Job ${job.id}: ${job.pageCount} pages, ${job.creditsCharged} credits`)
// 4. Poll until the job finishes.
let status
do {
await sleep(5000)
status = await (await api(`/jobs/${job.id}`)).json()
} while (status.status === 'queued' || status.status === 'processing')
if (status.status === 'failed') {
throw new Error(`${status.error} (credits returned: ${status.creditReturned})`)
}
// 5. Download the result as CSV.
const csv = await (await api(`/jobs/${job.id}/result?format=csv`)).text()
await writeFile('march-2026.csv', csv)
console.log('Saved march-2026.csv')
Start using the API
- Log in or sign up.
- Buy any credit pack on Credits & Billing. See the pricing page for pack sizes.
- Open Settings and click Create API key on the API access card.
- Optionally, add a webhook URL on the same card.
Questions about the API? Email support@statementpro.ai.
Create Your API Key
Any credit pack unlocks an API key in Settings. Purchased credits pay for each conversion, at 1 credit per 10 pages, rounded up.
Open Settings View credit packs