API Reference

Base URL: https://bankstatementboss.com/api/v1

Authentication: API key in request header:

X-Api-Key: YOUR_API_KEY

Formats: JSON requests and responses.

Output Formats: csv (default), quickbooks, xero, sage, json


Download Postman Collection

Verify API Key

Endpoint: GET /api/v1/verify

Auth: required

Use this endpoint to verify that your API key is valid. This does not use credits.

curl -X GET "https://bankstatementboss.com/api/v1/verify" \
  -H "X-Api-Key: YOUR_API_KEY"

Response:

{
  "success": true,
  "data": {
    "accountId": 1001,
    "plan": "pro",
    "status": "active",
    "credits": 1000,
    "outputFormat": "csv"
  },
  "error": null
}

Upload PDF

Endpoint: POST /api/v1/upload

Auth: required

Content-Type: multipart/form-data

Parameters:

  • file (required) – PDF file (max 50MB)
curl -X POST "https://bankstatementboss.com/api/v1/upload" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -F "file=January-2025.pdf"

Response:

{
  "success": true,
  "data": {
    "documentId": "e5a42e0e-8a68-4d91-a3e7-1d98f12970f2",
    "filename": "January-2025.pdf",
    "pages": 12,
    "status": "uploaded"
  },
  "error": null
}

Process PDF

Endpoint: POST /api/v1/process

Auth: required

Content-Type: application/json

Starts processing the uploaded PDF. Credits are deducted based on page count.

Body Parameters:

  • documentId (required) – The document UUID from upload
  • outputFormat (optional) – Output format: csv, quickbooks, xero, sage, or json
{
  "documentId": "e5a42e0e-8a68-4d91-a3e7-1d98f12970f2",
  "outputFormat": "json"
}
curl -X POST "https://bankstatementboss.com/api/v1/process" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"documentId":"e5a42e0e-8a68-4d91-a3e7-1d98f12970f2","outputFormat":"json"}'

Response:

{
  "success": true,
  "data": {
    "documentId": "e5a42e0e-8a68-4d91-a3e7-1d98f12970f2",
    "jobId": "abc123def456",
    "status": "processing",
    "estimatedPages": 12
  },
  "error": null
}

Check Status

Endpoint: GET /api/v1/status/{documentId}

Auth: required

Poll this endpoint to check processing status. When status is completed, the downloadUrl will be available.

curl -X GET "https://bankstatementboss.com/api/v1/status/e5a42e0e-8a68-4d91-a3e7-1d98f12970f2" \
  -H "X-Api-Key: YOUR_API_KEY"

Response (processing):

{
  "success": true,
  "data": {
    "documentId": "e5a42e0e-8a68-4d91-a3e7-1d98f12970f2",
    "filename": "January-2025.pdf",
    "status": "processing",
    "pages": 12,
    "created": "2025-01-24 19:02:11",
    "started": "2025-01-24 19:02:15",
    "processed": null,
    "downloadUrl": null
  },
  "error": null
}

Response (completed):

{
  "success": true,
  "data": {
    "documentId": "e5a42e0e-8a68-4d91-a3e7-1d98f12970f2",
    "filename": "January-2025.pdf",
    "status": "completed",
    "pages": 12,
    "created": "2025-01-24 19:02:11",
    "started": "2025-01-24 19:02:15",
    "processed": "2025-01-24 19:03:45",
    "downloadUrl": "https://bankstatementboss.com/api/v1/download/e5a42e0e-8a68-4d91-a3e7-1d98f12970f2"
  },
  "error": null
}

Download Results

Endpoint: GET /api/v1/download/{documentId}

Auth: required

Downloads the processed transaction data. The format is determined by the outputFormat specified during processing, or your account default.

curl -X GET "https://bankstatementboss.com/api/v1/download/e5a42e0e-8a68-4d91-a3e7-1d98f12970f2" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -o transactions.csv

Response: File download (CSV, JSON, etc.)

CSV Format (default, quickbooks, xero, sage):

Date,Description,Amount
01/15/2025,Purchase at Store,-25.00
01/16/2025,Deposit,100.00

JSON Format:

[
  {
    "date": "01/15/2025",
    "description": "Purchase at Store",
    "debit": 25.00,
    "credit": 0,
    "amount": -25.00
  },
  {
    "date": "01/16/2025",
    "description": "Deposit",
    "debit": 0,
    "credit": 100.00,
    "amount": 100.00
  }
]

Check Credits

Endpoint: GET /api/v1/credits

Auth: required

Check your account's remaining credits.

curl -X GET "https://bankstatementboss.com/api/v1/credits" \
  -H "X-Api-Key: YOUR_API_KEY"

Response:

{
  "success": true,
  "data": {
    "accountId": 1001,
    "plan": "pro",
    "status": "active",
    "credits": 755,
    "outputFormat": "csv"
  },
  "error": null
}

Error Handling

On failure, success is false and an error object is returned with a code and message.

{
  "success": false,
  "data": null,
  "error": {
    "code": "invalid_api_key",
    "message": "API key is invalid or missing."
  }
}

Common error codes:

  • invalid_api_key – API key missing or invalid
  • inactive_account – Account is inactive or suspended
  • invalid_plan – Plan does not support API access (Pro or Business required)
  • invalid_file – Missing or invalid PDF file
  • invalid_file_type – Only PDF files are allowed
  • document_not_found – Document does not exist
  • unauthorized – You don't have access to this document
  • insufficient_credits – Not enough credits to process
  • invalid_status – Document status must be 'uploaded' to process
  • not_ready – Document processing is not complete

Complete Workflow

Step 1: Upload PDF

POST /api/v1/upload
→ Returns: documentId

Step 2: Start Processing

POST /api/v1/process
Body: { "documentId": "...", "outputFormat": "json" }
→ Returns: jobId, status: "processing"

Step 3: Poll Status (every 5-10 seconds)

GET /api/v1/status/{documentId}
→ Returns: status, downloadUrl (when completed)

Step 4: Download Results

GET /api/v1/download/{documentId}
→ Returns: File download