Documentation

Statement API reference

Send a statement PDF, get back checked transactions, account details, a cash-flow summary and answers to your questions. Every number comes with the proof that it adds up.

Quickstart

Create an account and you get a test key straight away. Then:

curl https://api.sumproof.dev/v1/statements/parse \
  -H "Authorization: Bearer sp_test_YOUR_KEY" \
  -F "file=@statement.pdf"

Authentication

Send your key as Authorization: Bearer sp_live_…. Keys starting sp_test_ are free, read documents of up to 10 pages and have a monthly page cap. Keys starting sp_live_ spend credits. Keys are shown once, when you create them; keep them on your server, never in a browser or mobile app.

Parse a statement

POST/v1/statements/parse
Endpoint
POST https://api.sumproof.dev/v1/statements/parse
Content-Type: multipart/form-data
FieldWhereDescription
fileform, requiredThe statement PDF, up to 25 MB.
passwordformFor locked PDFs. Never stored or logged.
summaryquerytrue (default) adds the cash-flow summary.
formatqueryjson (default) or csv for the transactions only.

The call is synchronous for statements up to 60 pages: text pages are read from the PDF's layout in milliseconds, and pages that need the model are read in parallel. Longer statements are read in the background automatically: you get 202 Accepted with a job ("auto_async": true), exactly as if you had sent ?async=true, so no call ever waits on a long connection. Every response carries X-Request-Id.

Retry safely with an Idempotency-Key. Send any unique string (an order or application id works) in the Idempotency-Key header. If your call times out and you retry with the same key, you get the first answer again with Idempotent-Replayed: true: no second parse, no second charge. Keys are kept for 24 hours. The same key with a different file is refused; errors aren't stored, so you can retry them with the same key.

When every reader is busy you get 503 SERVER_BUSY with Retry-After, and nothing is charged. Big batches are smoothest with ?async=true and a webhook.

Query a statement

POST/v1/graphql

Ask a statement exactly what you need with GraphQL: the last 10 transactions, who paid the most, every credit over ₦50,000, month by month. Every answer is computed by code from the checked rows; no model touches the numbers. Queries are free: the parse already paid for the statement.

In the same call: send query (and optionally variables as JSON) with the PDF. The answer comes back as query_result, and nothing is stored.

Inline query
curl https://api.sumproof.dev/v1/statements/parse \
  -H "Authorization: Bearer sp_test_YOUR_KEY" \
  -F "file=@statement.pdf" \
  -F 'query={ statement { transactions(last: 10) { date description amount } } }'

Keep it and ask again: add ?retain_minutes=60 (up to 1440) to the parse call. The statement is kept encrypted and deleted at retained_until. Query it as often as you like with POST /v1/graphql.

POST /v1/graphql
{
  "query": "query ($id: String!) {
    statement(id: $id) {
      counterparties(direction: CREDIT, limit: 5) { name total count share }
      totals(filter: { direction: CREDIT, minAmount: 50000 }) { count credit median }
      transactions(filter: { contains: \"bet\" }, sort: AMOUNT_DESC, first: 5) { date description debit }
      months { month credit debit net closingBalance }
    }
  }",
  "variables": { "id": "stm_7a1e…" }
}

Filters on transactions, totals, counterparties and months: direction, minAmount, maxAmount, dateFrom, dateTo, contains, counterparty, flagged, page, section. Sort with STATEMENT, DATE_ASC, DATE_DESC, AMOUNT_DESC, AMOUNT_ASC, and page with first, last, offset. The full schema is at GET /v1/graphql/schema; point any GraphQL tool at it. Try it live in the playground's Query tab.

Or just ask in English. POST /v1/ask with a kept statement's id and a question, or send question with the PDF. The model only turns the question into a query; it never sees the statement. Our code runs the query on the checked rows, and you get the data, a one-line description of what was computed, and the exact query, so the answer can be repeated without the model.

POST /v1/ask
{ "statement_id": "stm_7a1e…", "question": "Who paid them the most since March?" }

→ {
  "answerable": true,
  "explanation": "The people who paid in the most from 1 March.",
  "query": "query ($id: String!) { statement(id: $id) { counterparties(direction: CREDIT, limit: 5, filter: { dateFrom: \"2026-03-01\" }) { name total count } } }",
  "data": { "statement": { "counterparties": [ … ] } }
}

Async jobs

GET/v1/jobs/{id}

For long statements, add ?async=true. You get 202 Accepted straight away with a job id, and the parse runs in the background. Fetch the result from GET /v1/jobs/{id} with the same key, or set a webhook and wait to be told. Results are kept encrypted for one hour after the job finishes, then deleted.

202 Accepted
{
  "id": "job_3f9c…",
  "object": "job",
  "status": "queued",
  "request_id": "stm_7a1e…",
  "poll_url": "https://api.sumproof.dev/v1/jobs/job_3f9c…"
}

status moves from queued to running to succeeded (with result, the same body a synchronous call returns) or failed (with error).

Webhooks

GET/v1/webhook/deliveries

Set one endpoint per account in Settings. When an async job ends we send statement.parsed or statement.failed. Events carry ids, status and counts, never statement data: fetch the result with your key.

Every event is logged before it is sent. If your endpoint doesn't answer with a 2xx within 10 seconds, we retry after 10 s, 1 min, 5 min, 30 min, 2 h and 6 h (seven tries over about 8.5 hours), and the log in Settings shows each attempt. Anything that still failed can be replayed, one by one or all at once, from Settings or from code.

POST to your endpoint
Sumproof-Signature: t=1763049000,v1=5c1e…
Sumproof-Event-Id: evt_9b2d…        same on every retry and replay
Sumproof-Delivery-Id: dlv_41aa…
Sumproof-Attempt: 1

{
  "id": "evt_9b2d…",
  "type": "statement.parsed",
  "created_at": "2026-11-13T15:10:00Z",
  "data": {
    "job_id": "job_3f9c…",
    "request_id": "stm_7a1e…",
    "status": "succeeded",
    "quality": "high",
    "reconciled": true,
    "transaction_count": 69,
    "pages": 3
  }
}

To verify, compute HMAC-SHA256 of <t>.<raw body> with your signing secret and compare it to v1. Reject events whose t is more than five minutes old. For a day after you rotate the secret the header carries two v1 values, signed with the new and the old secret: accept the event if either matches, so rotating never drops an event.

Handle each Sumproof-Event-Id once. Retries and replays reuse it, so storing the ids you have processed makes your handler safe to receive the same event twice.

Catch up after downtime
# What failed?
curl https://api.sumproof.dev/v1/webhook/deliveries?status=failed   -H "Authorization: Bearer $SUMPROOF_KEY"

# Send one again (new delivery, same event id)
curl -X POST https://api.sumproof.dev/v1/webhook/deliveries/dlv_41aa…/replay   -H "Authorization: Bearer $SUMPROOF_KEY"

# Or every failed event since a time (up to 100)
curl -X POST https://api.sumproof.dev/v1/webhook/deliveries/replay-failed   -H "Authorization: Bearer $SUMPROOF_KEY"   -H "Content-Type: application/json" -d '{"since": "2026-11-17T00:00:00Z"}'

The response

Top level: id, quality, quality_reasons, bank, account, transactions, checks, summary, usage. Each transaction:

FieldTypeMeaning
datestring (YYYY-MM-DD)Transaction date. dd/mm vs mm/dd is settled once for the whole statement.
value_datestring | nullValue date, when printed.
descriptionstringNarration, with wrapped lines joined.
referencestring | nullReference or cheque number, when printed.
debit / creditnumber | nullMoney out / in, always positive. Units, not kobo.
amountnumber | nullcredit − debit: positive in, negative out.
balancenumber | nullRunning balance printed on the row.
pagenumberPage the row was read from.
sourcetable | llm | visionHow the row was read: page layout, model from the text layer, or model from the page image.
flagsstring[]Anything we could not confirm: balance_break, not_verbatim, date_unreadable, unsigned_amount…
rawobjectThe strings exactly as printed, for audit.

Checks and quality

checks.reconciled is true when every printed balance equals the previous balance plus credits minus debits, to the kobo. Breaks are listed in running_balance_breaks with the expected and printed balance. opening_plus_flows_equals_closing and printed_totals_match compare the rows with the figures printed on the statement; they are null when the statement doesn't print them. verbatim_failures lists rows where a value the model returned is not on the page.

quality is high when everything checks out, medium when something couldn't be checked (no running balance, a scanned page, a missing DR/CR marker), and low when a check failed in a way that matters. A low-quality result is still a 200: you decide whether to use it. A common rule is: auto-accept high, send the rest for review.

Summary

Computed from the returned transactions only, so you can reproduce every figure: totals, a month-by-month table with closing balances, average daily balance, days below zero, the largest credits and debits, recurring credits and debits (same payer, similar amount, 3 or more months), how concentrated the money coming in is, and counts of betting, loan-app and reversal transactions. There are no credit scores.

Insights

Every response with the summary also carries insights: what a credit officer would conclude, computed from the checked rows. Nothing is a score or a decision, and every figure comes with the rows behind it.

income: the salary (or main regular income) with its typical amount, pay day and months seen, other regular income, and the median month's money in. Savings moves and loan disbursements are never counted as income. obligations: loan repayments, rent and bills seen in at least two months (regular everyday spending is listed but not counted). affordability: monthly income, obligations, free cash, obligations-to-income, average daily balance and days below zero.

patterns lists six checks, each with detected, a severity (none, watch, high), a plain-English detail, its numbers and evidence (row indexes):

  • inflated_turnover: money that comes in and leaves again within two days for about the same amount.
  • parked_funds: a big credit near the end that lifts the closing balance far above the account's normal balance.
  • loan_stacking: activity with several digital lenders.
  • betting: betting debits, as a share of money out and per month.
  • salary_drift: missed salary months, amounts that move, a pay day that wanders, a falling latest salary.
  • edited_statement: an editing tool in the PDF's own details, a file changed after it was made, totals or counts that disagree with the bank's print, balances that don't chain.

Insights are also in GraphQL (statement { insights }), so plain-English questions like "does this person have a steady salary?" work too. The dashboard's Report tab shows them on one page you can save as a PDF.

Controls

For the account (Settings → Controls): No AI (every page is read on our servers only, scans included through free OCR; English questions are off), a monthly spend cap in paid credits, the longest a statement may be kept for questions, and alert emails for low credits and failing webhooks.

For each key (API keys → Edit): allowed IP addresses or ranges, an expiry date, and defaults for format, summary and No AI. A request can still ask for something else explicitly. Every English question and GraphQL query is listed on the Queries page for 30 days (the question and the query, never the answer); GET /v1/queries returns the same list.

Errors

Error shape
{
  "error": {
    "code": "PDF_PASSWORD_REQUIRED",
    "message": "This PDF is password-protected. Send the password in the `password` field.",
    "request_id": "stm_9f1c…"
  }
}
CodeHTTPWhen
UNAUTHORIZED401Missing, wrong or revoked API key.
EMAIL_NOT_VERIFIED403Live keys and buying credits need a confirmed email.
JOB_INTERRUPTED500An async job was cut off by a server restart. Send it again; nothing was charged.
PDF_PASSWORD_REQUIRED422The PDF is locked. Send `password` with the file.
PDF_PASSWORD_WRONG422The password didn't open the PDF.
PDF_UNREADABLE422The file is damaged or took too long to read.
NOT_A_STATEMENT422No transaction table was found.
MODEL_TIER_UNAVAILABLE422A scanned statement reached a server without the model tier.
MODEL_TEMPORARILY_UNAVAILABLE503Our reading model couldn't be reached. Nothing was charged; retry shortly.
UNSUPPORTED_FILE415The file is not a PDF.
FILE_TOO_LARGE413Over 25 MB.
TOO_MANY_PAGES413Over the page limit (300 live, 10 with a test key).
INSUFFICIENT_CREDITS402Not enough credits for this statement.
TEST_LIMIT_REACHED429The monthly test allowance is used up, or the document is too long for a test key.
RATE_LIMITED429Over 60 requests a minute on this key. See `Retry-After`.
VALIDATION_FAILED400A field is missing or invalid. `details.fields` says which.
USE_ASYNC422A long statement asked for CSV, a query or a question in one call. Send it with `?async=true`.
SERVER_BUSY503Every reader is busy. Nothing was charged; retry after `Retry-After` seconds, or send it async.
IDEMPOTENCY_IN_PROGRESS409A request with the same Idempotency-Key is still running. Retry shortly.
IDEMPOTENCY_KEY_REUSED422The same Idempotency-Key was sent with a different file or options.
SPEND_CAP_REACHED402The account's monthly spend cap is reached. Raise it in Settings → Controls.
KEY_EXPIRED401This key passed its expiry date. Create a new one.
IP_NOT_ALLOWED403The key is limited to other IP addresses (Keys → Edit).
AI_DISABLED403No AI is on for this account or key, so English questions are off. GraphQL still works.
PARSE_FAILED500Our fault. Quote `request_id` when you contact us.

You are only charged for successful parses. Errors never cost credits.

Credits and limits

1 credit reads one text page; a scanned page uses 3. Every account gets 100 free credits each calendar month, spent before paid credits. Paid credits never expire. Live keys read up to 300 pages per document; test keys up to 10. The rate limit is 60 requests a minute per key.

Banks

The parser reads any statement with a transaction table. These are the names it recognises for bank; "untested" means it works with the general engine but hasn't been confirmed on a real statement from that bank yet.

Loading…

Privacy

Statements are read in memory and dropped when the response is sent. We keep a log of each request with counts, timings, the bank name and any error code: never the file, its text, names, account numbers or passwords. Pages that need the model are sent to our model provider, Anthropic, under its API data terms; pages read from the layout never leave our server. If you report a wrong parse you can choose to attach the file; it is used only to fix the parser. You must have your end user's consent to process their statement.

Something unclear or missing? Tell us, we read every message.