# Sumproof API reference

Sumproof is an API that turns documents into data you can trust: every number is proven by checking the arithmetic, such as a running balance that must chain from row to row. Bank statements are the first supported document type.

Base URL: `https://api.sumproof.dev`. Interactive OpenAPI: `https://api.sumproof.dev/v1/docs`. Human docs: https://www.sumproof.dev/docs.

## Authentication
Send `Authorization: Bearer <key>`. Keys starting `sp_test_` are free: documents up to 10 pages and 300 pages a month. Keys starting `sp_live_` spend credits and read documents up to 300 pages. Keys are shown once when created. Keep them on your server, never in a browser or mobile app. Create a key by signing up at https://www.sumproof.dev/signup.

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

## Parse a statement: POST /v1/statements/parse
Multipart form. Returns JSON (or CSV) with transactions, checks, a summary and insights.

| Field | Where | Description |
|---|---|---|
| `file` | form, required | The statement PDF, up to 25 MB. |
| `password` | form | For locked PDFs. Never stored or logged. |
| `summary` | query | `true` (default) adds the cash-flow summary and insights. |
| `format` | query | `json` (default) or `csv` for the transactions only. |
| `async` | query | `true` returns `202` with a job to poll. |
| `retain_minutes` | query | Keep the statement encrypted for follow-up queries, up to 1440. |
| `query` / `variables` | form | An inline GraphQL query answered in the same call (`query_result`). |
| `question` | form | A question in English answered in the same call. |
| `Idempotency-Key` | header | Any unique string. A retry with the same key returns the first answer (`Idempotent-Replayed: true`) with no second parse and no second charge. Kept 24 hours. |

Statements up to 60 pages are answered synchronously. Longer ones are read in the background automatically: you get `202 Accepted` with a job (`"auto_async": true`). When every reader is busy you get `503 SERVER_BUSY` with `Retry-After` and nothing is charged. Every response carries `X-Request-Id`.

## Query and ask
- GraphQL: `POST https://api.sumproof.dev/v1/graphql` with `{ "query": "...", "variables": { "id": "stm_..." } }`. Schema: `GET /v1/graphql/schema`. Root fields include `statement { transactions, totals, counterparties, months, insights }`. Filters: direction, minAmount, maxAmount, dateFrom, dateTo, contains, counterparty, flagged, page, section. Sort: STATEMENT, DATE_ASC, DATE_DESC, AMOUNT_DESC, AMOUNT_ASC. Page with first, last, offset.
- A statement must be kept first (`?retain_minutes=60`) to be queried by id, or send `query` with the PDF.
- English: `POST https://api.sumproof.dev/v1/ask` with `{ "statement_id": "stm_...", "question": "Who paid them the most since March?" }`. The model only turns the question into a query. Our code runs it on the checked rows and returns `answerable`, `explanation`, the exact `query` and the `data`.
- Every English question and GraphQL query is listed for 30 days (the question and the query, never the answer) at `GET /v1/queries`.

## Async jobs: GET /v1/jobs/{id}
Returns `status`: `queued`, `running`, `succeeded` (with `result`, the same body a synchronous call returns) or `failed` (with `error`). Results are kept encrypted for 1 hour after the job finishes.

## Webhooks
One endpoint per account, set in the dashboard. When an async job ends we send `statement.parsed` or `statement.failed`. Events carry ids, status and counts, never statement data. Each event is stored before it is sent. If your endpoint does not answer 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). Failed events can be replayed one by one or all at once.

Headers: `Sumproof-Signature: t=<unix>,v1=<hex>`, `Sumproof-Event-Id` (same on every retry and replay), `Sumproof-Delivery-Id`, `Sumproof-Attempt`. Verify: HMAC-SHA256 of `<t>.<raw body>` with your signing secret, compare to `v1`, reject timestamps more than five minutes old. For 24 hours after a secret rotation the header carries two `v1` values; accept the event if either matches. Handle each `Sumproof-Event-Id` once.

```bash
curl https://api.sumproof.dev/v1/webhook/deliveries?status=failed -H "Authorization: Bearer $SUMPROOF_KEY"
curl -X POST https://api.sumproof.dev/v1/webhook/deliveries/dlv_.../replay -H "Authorization: Bearer $SUMPROOF_KEY"
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`, `insights`, `usage`. Each transaction:

| Field | Type | Meaning |
|---|---|---|
| `date` | `string (YYYY-MM-DD)` | Transaction date. dd/mm vs mm/dd is settled once for the whole statement. |
| `value_date` | `string \| null` | Value date, when printed. |
| `description` | `string` | Narration, with wrapped lines joined. |
| `reference` | `string \| null` | Reference or cheque number, when printed. |
| `debit / credit` | `number \| null` | Money out / in, always positive. Units, not kobo. |
| `amount` | `number \| null` | credit − debit: positive in, negative out. |
| `balance` | `number \| null` | Running balance printed on the row. |
| `page` | `number` | Page the row was read from. |
| `source` | `table \| llm \| vision` | How the row was read: page layout, model from the text layer, or model from the page image. |
| `flags` | `string[]` | Anything we could not confirm: balance_break, not_verbatim, date_unreadable, unsigned_amount… |
| `raw` | `object` | The 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 figures printed on the statement and are `null` when the statement does not 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 could not 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 HTTP 200. A common rule: auto-accept `high`, send the rest for review.

## Summary and insights
The summary is computed from the returned transactions only: totals, month by month with closing balances, average daily balance, days below zero, largest credits and debits, recurring credits and debits, how concentrated the money coming in is, and counts of betting, loan-app and reversal transactions. There are no credit scores.

`insights` holds `income` (salary or main regular income, pay day, months seen), `obligations` (loan repayments, rent and bills seen in at least two months), `affordability` (income, obligations, free cash, obligations-to-income) and six `patterns`, each with `detected`, `severity` (none, watch, high), `detail`, `numbers` and `evidence` (row indexes): `inflated_turnover`, `parked_funds`, `loan_stacking`, `betting`, `salary_drift`, `edited_statement`.

## Controls
Account (dashboard Settings > Controls): No AI, a monthly spend cap in paid credits, the longest a statement may be kept, alert emails for low credits and failing webhooks. Per key: allowed IP addresses or ranges, an expiry date, and defaults for `format`, `summary` and No AI.

## Errors
Shape: `{ "error": { "code": "PDF_PASSWORD_REQUIRED", "message": "...", "request_id": "stm_..." } }`. You are charged only for successful parses.

| Code | HTTP | When |
|---|---|---|
| `UNAUTHORIZED` | 401 | Missing, wrong or revoked API key. |
| `EMAIL_NOT_VERIFIED` | 403 | Live keys and buying credits need a confirmed email. |
| `JOB_INTERRUPTED` | 500 | An async job was cut off by a server restart. Send it again; nothing was charged. |
| `PDF_PASSWORD_REQUIRED` | 422 | The PDF is locked. Send `password` with the file. |
| `PDF_PASSWORD_WRONG` | 422 | The password didn't open the PDF. |
| `PDF_UNREADABLE` | 422 | The file is damaged or took too long to read. |
| `NOT_A_STATEMENT` | 422 | No transaction table was found. |
| `MODEL_TIER_UNAVAILABLE` | 422 | A scanned statement reached a server without the model tier. |
| `MODEL_TEMPORARILY_UNAVAILABLE` | 503 | Our reading model couldn't be reached. Nothing was charged; retry shortly. |
| `UNSUPPORTED_FILE` | 415 | The file is not a PDF. |
| `FILE_TOO_LARGE` | 413 | Over 25 MB. |
| `TOO_MANY_PAGES` | 413 | Over the page limit (300 live, 10 with a test key). |
| `INSUFFICIENT_CREDITS` | 402 | Not enough credits for this statement. |
| `TEST_LIMIT_REACHED` | 429 | The monthly test allowance is used up, or the document is too long for a test key. |
| `RATE_LIMITED` | 429 | Over 60 requests a minute on this key. See `Retry-After`. |
| `VALIDATION_FAILED` | 400 | A field is missing or invalid. `details.fields` says which. |
| `USE_ASYNC` | 422 | A long statement asked for CSV, a query or a question in one call. Send it with `?async=true`. |
| `SERVER_BUSY` | 503 | Every reader is busy. Nothing was charged; retry after `Retry-After` seconds, or send it async. |
| `IDEMPOTENCY_IN_PROGRESS` | 409 | A request with the same Idempotency-Key is still running. Retry shortly. |
| `IDEMPOTENCY_KEY_REUSED` | 422 | The same Idempotency-Key was sent with a different file or options. |
| `SPEND_CAP_REACHED` | 402 | The account's monthly spend cap is reached. Raise it in Settings → Controls. |
| `KEY_EXPIRED` | 401 | This key passed its expiry date. Create a new one. |
| `IP_NOT_ALLOWED` | 403 | The key is limited to other IP addresses (Keys → Edit). |
| `AI_DISABLED` | 403 | No AI is on for this account or key, so English questions are off. GraphQL still works. |
| `PARSE_FAILED` | 500 | Our fault. Quote `request_id` when you contact us. |

## 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. Rate limit: 60 requests a minute per key. Max file 25 MB.

## Banks
Recognised by name (30): GTBank, Access Bank, Zenith Bank, UBA, First Bank, FCMB, Fidelity Bank, Stanbic IBTC, Sterling Bank, Union Bank, Wema Bank, Ecobank, Polaris Bank, Keystone Bank, Unity Bank, Providus Bank, Standard Chartered, Heritage Bank, Jaiz Bank, Globus Bank, Titan Trust Bank, Kuda, Moniepoint, OPay, PalmPay, VFD Microfinance Bank, Carbon, FairMoney, SmartCash PSB, MoMo PSB. The parser reads any statement with a transaction table. Confirmed on real statements so far: First Bank, OPay, SmartCash PSB. List: `GET /v1/banks`, page: https://www.sumproof.dev/banks.

## Privacy
Statements are read in memory and dropped when the response is sent. The request log keeps counts, timings, the bank name and error codes, never the file, its text, names, account numbers or passwords. Pages that need a model are sent to Anthropic under its API data terms; pages read from the layout never leave our server. You must have your end user's consent to process their statement.
