Skip to content
DocsGet started

Test mode

A test key returns a fixture document instead of reading the file you send. It is free, it does not touch your free pages or your cap, and it can return any error code on demand.

Send a request#

Take an sb_test_ key from the console. Same endpoint, same host, same headers. Send any file the API accepts: it is checked for size and type and then discarded unread.

# Any PDF will do. It is checked and then discarded.
curl -X POST https://statementbear.com/api/v1/documents \
  -H "Authorization: Bearer $STATEMENTBEAR_TEST_KEY" \
  -H "Content-Type: application/pdf" \
  --data-binary @anything.pdf

# Ask for a specific document, or force an error.
curl -X POST https://statementbear.com/api/v1/documents \
  -H "Authorization: Bearer $STATEMENTBEAR_TEST_KEY" \
  -H "X-Test-Scenario: credit_card" \
  -H "Content-Type: application/pdf" \
  --data-binary @anything.pdf

Scenarios#

Send X-Test-Scenario to choose what comes back. Omit it for bank.

ScenarioReturnsWhat it is
bank200A single current account, reconciled. The default when no header is sent.
credit_card200A card statement. Its credits are the repayment and a refund, so it is what to test your income filter against.
multi_account200A checking and a savings account on one document, with a transfer printed on both sides.
unreconciled200A document whose figures did not reconcile. Exercises your manual review path.
suspicious200An unreconciled document with authenticity.risk high: edited in a PDF editor, modified after creation, balances that do not follow. Exercises your fraud review path.
not_a_bank_statement422The file was readable and is not a statement.
password_required422The PDF is password-protected and no password was sent.
incorrect_password422The password sent does not open the PDF.
parse_failed500Our error. Retry it.
free_pages_exhausted402The free pages are spent and no payment method is on file.
not_enough_free_pages402Some free pages are left, fewer than the file has, and no payment method is on file.
monthly_cap_reached402The file would pass the monthly page cap.
canceled402Billing for the account was cancelled.
too_many_concurrent_requests429Too many documents in flight. Exercises your backoff.
file_too_large413Over the size limit, without uploading 50MB to find out.

An unknown value returns 400 unknown_test_scenario and the message lists every valid one. The parsing MCP server takes the same names in its test_scenario argument.

Telling a fixture apart#

Every document carries livemode. It is false on a fixture and true on a real read. Store it with whatever you read the document for.

200 OK, from a test key
{
  "id": "doc_test_9c41f0a2b8e37c94d0a1b2c3",
  "object": "document",
  "status": "succeeded",
  "livemode": false,
  "currency": "GBP",
  "issuer": { "name": "Monzo", "domain": "monzo.com" },
  "accounts": [ ... ],
  "verification": { "reconciled": true, "issues": [] },
  "authenticity": { "risk": "low", "signals": [], ... },
  "usage": { "pages": 3, "billablePages": 0 }
}

A fixture's id starts doc_test_. Everything else about a scenario except created is the same on every call, so it is safe to assert on in a snapshot test.

What is the same#

  • Authentication, including 401 for a missing or revoked key.
  • The size and type checks on your upload. A file the API does not read still returns 415.
  • async=true: a 202 with status: "processing", then succeeded a couple of seconds later.
  • Webhooks, sent to your test endpoints only. See Webhooks.
  • Stored documents: list, fetch and delete them like live ones. A test key sees only test documents.
  • Collections: a test collection's hosted page works, and every upload returns the bank fixture.
  • Idempotency-Key, including replays, Idempotent-Replayed: true and the 409 after 24 hours.
  • The response envelope, the error codes and every header.
  • Logs in your console, so a test call shows up like any other.

What is different#

  • The file you send is never read. The response is a fixture.
  • Nothing is billed. X-Billable-Pages and usage.billablePages are always 0.
  • Your free pages and monthly cap are untouched.
  • Test keys keep working when billing is cancelled.
  • Concurrency is not limited. Up to 120 test requests per minute instead.

Idempotency keys#

An idempotency key is scoped to the mode that used it. The same string can be used once in test and once for real, and neither replays the other.

Going live#

  1. Swap sb_test_ for sb_live_ in your secret store.
  2. Remove X-Test-Scenario. A live key sends it back as 400 test_scenario_on_live_key, and nothing is read or charged.
  3. Add a live webhook endpoint with its own secret. A test endpoint never receives live events.
  4. Check that whatever you store records livemode.
  5. Work through the rest of Going live.
Something wrong or missing on this page? [email protected]