Skip to main content
Public API

Developer Documentation

Integrate parsing, reconciliation, exports, and webhook-driven workflows into your app, plugin, or finance operations stack.

Quick Start

  1. Go to API Keys and create a new key.
  2. Include the key in the Authorization header: Bearer bsm_YOUR_KEY
  3. POST your bank statement to /api/v1/jobs
  4. Poll GET /api/v1/jobs/{id} or listen via webhooks for results

Authentication

All API requests require authentication via an API key sent in the Authorization header:

Authorization: Bearer bsm_YOUR_API_KEY

API keys can be scoped to specific permissions:

  • jobs:read — Read job status and results
  • jobs:write — Create new parsing jobs
  • webhooks:manage — Create/delete webhook endpoints
  • export:read — Export data as CSV/JSON
  • usage:read — Read usage statistics

Code Examples

curl -X POST https://bankstatementmatcher.com/api/v1/jobs \
  -H "Authorization: Bearer bsm_YOUR_API_KEY" \
  -F "file=@bank_statement.pdf"

API Reference

MethodEndpointDescription
POST/api/v1/jobsUpload a bank statement for parsing
GET/api/v1/jobsList your parsing jobs
GET/api/v1/jobs/{id}Get job status and details
GET/api/v1/jobs/{id}/resultsGet parsed transactions
GET/api/v1/jobs/{id}/exportExport results as CSV/JSON
GET/api/v1/usageCheck API usage for the month
GET/api/v1/statusHealth check and plan info
POST/api/v1/webhooksRegister a webhook endpoint
GET/api/v1/webhooksList webhook endpoints
DELETE/api/v1/webhooks/{id}Delete a webhook
POST/api/v1/webhooks/testSend a test webhook event

Webhooks

Instead of polling, register webhook endpoints to receive real-time notifications. All payloads are signed with HMAC-SHA256 using your signing secret.

Events

job.createdA new parsing job has been submitted
job.completedJob finished successfully — results are ready
job.failedJob failed to process
job.reviewJob needs manual review
usage.thresholdMonthly usage approached or exceeded limit

Payload Example

{
  "event": "job.completed",
  "data": {
    "job_id": "abc123",
    "status": "completed",
    "bank_name": "Chase",
    "transactions_count": 42,
    "created_at": "2025-01-15T10:30:00Z"
  },
  "timestamp": "2025-01-15T10:31:15Z"
}

Signature Verification

Each delivery includes these headers: X-BSM-Signature, X-BSM-Timestamp, X-BSM-Delivery-Id. Compute HMAC-SHA256(signing_secret, "{timestamp}.{body}") and compare.

Rate Limits

PlanRequests / Minute
Free10
Starter60
Pro200
Business1,000

If you exceed the limit you'll get a 429 Too Many Requests response. Wait and retry with exponential backoff.

Plugins & SDKs

WooCommerce
WordPress plugin for WooCommerce stores
Shopify
Shopify app for bank reconciliation
WordPress
Standalone WordPress plugin
Zapier
Connect with 5,000+ apps
Python SDK
pip install bsm-sdk
Node.js SDK
npm install @bsm/node-sdk
PHP SDK
composer require bsm/php-sdk

Response Format

All responses use a consistent JSON envelope:

{
  "ok": true,
  "data": { ... },
  "meta": {
    "request_id": "req_abc123"
  }
}

Error responses set "ok": false and include a "detail" field with a human-readable message.