Documents

Upload a bank statement PDF

Upload a PDF bank statement for conversion. The file is processed asynchronously. Poll the returned id via GET /v1/documents/{id} to check progress. Rate limit: 10 requests per minute. Alternatively, POST a JSON body { "upload_id": "..." } referencing a token minted via POST /v1/upload-tokens, to convert a previously-PUT file by reference.

post/documents

Request

  • Base URL: https://api.bankstatemently.com/v1
  • URL: https://api.bankstatemently.com/v1/documents
  • Auth: API key in header X-API-Key

Query parameters

retry'true'

Set to 'true' to reprocess a previously failed upload of the same file. Without this, re-uploading a failed file returns an already_processing error.

Headers

Idempotency-Keystring

A unique key to ensure the request is processed at most once. Must be unique per request — use a UUID. Keys expire after 24 hours. If a duplicate key is detected, the original response is replayed with X-Idempotency-Replayed: true.

X-Filenamestring

Original filename for the uploaded PDF. Used for display purposes only. Defaults to 'document.pdf' if not provided.

X-Webhook-URLstring uri

Webhook URL for processing completion notifications. Overrides the default webhook URL configured on the API key.

X-Passwordstring

Decryption password for encrypted PDFs. When provided, the PDF is decrypted and processed in a single request — no need for the two-step unlock flow. The password is used in memory only and never stored or logged.

Request body

upload_idstring required

An upload_id from POST /v1/upload-tokens, after PUTting the file to its upload_url. Converts the previously-uploaded file by reference instead of sending PDF bytes in this request.

webhook_urlstring uri

Webhook URL for processing completion notifications. Overrides the default webhook URL configured on the API key.

Response

Upload accepted. Processing has started, or the PDF requires a password.

idstring uuid required

Unique document identifier. Use this to poll status and request exports.

status'processing' | 'completed' | 'failed' | 'password_required' required

The processing status of a document.

contentHashstring required

Content-addressable hash of the uploaded file.

createdAtstring date-time required

Timestamp when the document was created.

Changes

No recorded changes to this operation across all 1 revision of this API.