Bank Statement Analyzer API

Our REST API enables businesses to programmatically manage and analyze bank statements for multiple entities. Perfect for accounting firms, financial advisors, and companies managing multiple departments or clients.

Key Features:

  • Multi-entity support for managing different clients or departments
  • Automated bank statement processing and transaction extraction
  • Detailed financial analysis and categorization
  • Support for multiple currencies and statement formats
  • Both JSON API and HTML visualization options
Swagger UI (Technical API Reference) ReDoc (Detailed Documentation)

Getting Started

Before you begin, make sure you have:

  • An API account with credentials
  • Sufficient credit tokens (4 credits per statement analysis)
  • Bank statements in PDF format (up to 10MB per file)

Understanding Entities

In our API, an "entity" represents a distinct business unit you're analyzing statements for. This could be:

  • Different clients (for accounting firms)
  • Company departments or cost centers
  • Individual business units or franchises

Each entity has its own collection of bank statements and transactions, allowing for separate analysis and reporting. Entities are automatically created when you upload your first statement with a new entity_id - there's no need to explicitly create them first.

Credit System

Our credit system ensures fair usage of the API:

  • Each statement analysis requires 4 credits
  • 3 credits are deducted at upload time
  • 1 credit is deducted after successful processing
  • Failed processing returns all credits

Quick Start Guide

Follow these steps to start analyzing bank statements through our API. Each step includes example requests and responses.

  1. 1. Authentication

    First, authenticate with your credentials to get JWT tokens. These tokens will be used for all subsequent requests.

    POST /api/v1/token/

    Request:

    {
    "username": "your_username",
    "password": "your_password"
}

    Response:

    {
    "access": "eyJ0eXAiOiJKV1QiLCJhbGc...",  # Valid for 1 hour
    "refresh": "eyJ0eXAiOiJKV1QiLCJhbGc..."  # Valid for 24 hours
}
  2. 2. Upload a Bank Statement

    Upload a bank statement PDF and specify your entity ID. If this is a new entity ID, it will be automatically created. Each upload requires 4 credits and initiates automated processing.

    POST /api/v1/statements/

    cURL Example:

    curl -X POST \
    -H "Authorization: Bearer your_access_token" \
    -H "Content-Type: multipart/form-data" \
    -F "[email protected]" \
    -F "entity_id=client123" \
    https://bankstatement.app/api/v1/statements/

    Python Example:

    import requests

url = "https://bankstatement.app/api/v1/statements/"
headers = {"Authorization": "Bearer your_access_token"}
files = {"file": open("statement.pdf", "rb")}
data = {"entity_id": "client123"}

response = requests.post(url, headers=headers, files=files, data=data)

    Success Response:

    {
    "id": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
    "entity_id": "client123",
    "uploaded_at": "2024-03-20T14:30:00Z",
    "processing_status": "pending",
    "is_processed": false
}

    Note: The entity_id will be automatically created if it doesn't exist. Bank name and currency will be automatically detected during processing.

  3. 4. Monitor Processing Status

    Check the processing status of your uploaded statement. Processing typically takes 30-60 seconds.

    GET
    /api/v1/entities/ {entity_id} /statements/ {statement_id} /

    Example Response (Processing):

    {
    "id": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
    "processing_status": "processing",
    "is_processed": false,
    "pages_processed": 2,
    "total_pages": 5
}

    Example Response (Completed):

    {
    "id": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
    "processing_status": "completed",
    "is_processed": true,
    "pages_processed": 5,
    "total_pages": 5,
    "processing_time": 45.2,
    "transaction_count": 50,
    "date_range": {
        "start": "2024-02-01",
        "end": "2024-02-29"
    }
}

    Pro Tip: Poll this endpoint every 5 seconds until processing_status is either "completed" or "failed".

  4. 4. Access Transactions

    Once processing is complete, retrieve the extracted transactions with optional filtering.

    GET
    /api/v1/entities/ {entity_id} /transactions/

    Available Filters:

    start_date=2024-02-01    # Filter by date range
end_date=2024-02-29
currency=USD             # Filter by currency
category=groceries      # Filter by category
min_amount=100         # Filter by amount
max_amount=1000

    Example Response:

    {
    "count": 50,
    "next": "https://bankstatement.app/api/v1/entities/client123/transactions/?page=2",
    "previous": null,
    "results": [
        {
            "id": "550e8400-e29b-41d4-a716-446655440000",
            "date": "2024-02-15",
            "description": "WALMART GROCERY",
            "amount": -124.56,
            "category": "groceries",
            "is_recurring": true,
            "statement_id": "f47ac10b-58cc-4372-a567-0e02b2c3d479"
        },
        // ... more transactions
    ]
}

    Pro Tip: Use the Accept header to get either JSON or HTML visualization:
    Accept: application/json or Accept: text/html

  5. 5. Get Entity Analysis

    View aggregated financial analysis across all statements for an entity.

    GET
    /api/v1/entities/ {entity_id} /

    Optional Query Parameters:

    start_date=2024-01-01    # Analysis period start
end_date=2024-02-29     # Analysis period end
currency=USD            # Specific currency

    Example Response:

    {
    "entity_id": "client123",
    "statement_count": 5,
    "total_income": 25000.00,
    "total_expenses": 18245.67,
    "net_position": 6754.33,
    "currency": "USD",
    "category_breakdown": [
        {
            "category": "groceries",
            "total": 2450.23,
            "transaction_count": 45,
            "percentage": 13.4
        },
        {
            "category": "utilities",
            "total": 1875.90,
            "transaction_count": 12,
            "percentage": 10.3
        }
    ],
    "monthly_summary": [
        {
            "month": "2024-01",
            "income": 12500.00,
            "expenses": 9123.45
        },
        {
            "month": "2024-02",
            "income": 12500.00,
            "expenses": 9122.22
        }
    ],
    "date_range": {
        "start": "2024-01-01",
        "end": "2024-02-29"
    }
}

    Pro Tip: Request HTML format for beautiful visualizations including charts and graphs.

Authentication

The API uses JWT (JSON Web Tokens) for authentication. Include your access token in the Authorization header of each request. Access tokens expire after 1 hour, use your refresh token to get a new one.

POST /api/v1/token/refresh/ 
{
    "refresh": "your_refresh_token"
}

Core Resources

Entities

Entities represent distinct business units (clients, departments, etc.) that you're analyzing statements for.

List Entities

GET
/api/v1/entities

Lists all entities you have access to.

Response Format
{
    "count": 2,
    "next": null,
    "previous": null,
    "results": [
        {
            "id": "client123",
            "name": "ACME Corp",
            "statement_count": 5,
            "last_upload": "2024-03-20T14:30:00Z"
        }
    ]
}

Get Entity Details

GET
/api/v1/entities/ {entity_id}

Retrieves detailed information about a specific entity.

Path Parameters
entity_id The unique identifier of the entity
Response Format
{
    "entity_id": "client123",
    "name": "ACME Corp",
    "statement_count": 5,
    "total_income": 25000.00,
    "total_expenses": 18245.67,
    "net_position": 6754.33
}

Bank Statements

Bank statements are PDF documents that contain transaction data. Each statement is processed to extract transactions and perform analysis.

List Statements

GET
/api/v1/entities/ {entity_id} /statements

Lists all bank statements for a specific entity.

Path Parameters
entity_id The unique identifier of the entity
Query Parameters
processing_status Filter by status (pending, processing, completed, failed)
currency Filter by currency (e.g., USD, EUR)
ordering Sort by field (e.g., -uploaded_at for newest first)
Response Format
{
    "count": 2,
    "next": null,
    "previous": null,
    "results": [
        {
            "id": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
            "entity_id": "client123",
    "bank_name": "Chase",
            "currency": "USD",
            "uploaded_at": "2024-03-20T14:30:00Z",
            "processing_status": "completed",
            "is_processed": true,
            "transaction_count": 50,
            "date_range": {
                "start": "2024-02-01",
                "end": "2024-02-29"
            }
        }
    ]
}

Upload Statement

POST /api/v1/statements/

Upload a new bank statement for processing. Requires 4 credits. Bank name and currency will be automatically detected during processing.

Request Body
file PDF file (max 10MB) Required
entity_id ID of the entity to associate with Required
Example Request

cURL Example:

curl -X POST \
    -H "Authorization: Bearer your_access_token" \
    -H "Content-Type: multipart/form-data" \
    -F "[email protected]" \
    -F "entity_id=client123" \
    https://bankstatement.app/api/v1/statements/

Python Example:

import requests

url = "https://bankstatement.app/api/v1/statements/"
headers = {"Authorization": "Bearer your_access_token"}
files = {"file": open("statement.pdf", "rb")}
data = {"entity_id": "client123"}

response = requests.post(url, headers=headers, files=files, data=data)
Response Format (201 Created)
{
    "id": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
    "entity_id": "client123",
    "uploaded_at": "2024-03-20T14:30:00Z",
    "processing_status": "pending",
    "is_processed": false
}
Error Responses
Status Description
400 Bad Request Invalid input (e.g., missing file or entity_id)
402 Payment Required Insufficient credits
413 Payload Too Large File exceeds 10MB limit
415 Unsupported Media Type File is not a PDF

Important: Statement processing is asynchronous. Bank name and currency will be automatically detected. Monitor the processing status using the returned statement ID.

Transactions

Access transaction data extracted from bank statements. Transactions are automatically processed and categorized.

List Transactions

GET
/api/v1/entities/ {entity_id} /transactions

Lists all transactions for a specific entity.

Path Parameters
entity_id The unique identifier of the entity
Query Parameters
statement_id Filter by statement ID
date_from Filter by date range start (YYYY-MM-DD)
date_to Filter by date range end (YYYY-MM-DD)
category Filter by transaction category
min_amount Filter by minimum amount
max_amount Filter by maximum amount
ordering Sort by field (e.g., -date, amount)

Response:

{
    "count": 1,
    "next": null,
    "previous": null,
    "results": [
        {
            "id": "t123e456-7890-4def-b123-456789abcdef",
            "statement_id": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
            "entity_id": "client123",
            "date": "2024-02-15",
            "description": "PAYMENT TO VENDOR XYZ",
            "amount": -1500.00,
            "currency": "USD",
            "category": "business_expense",
            "metadata": {
                "page_number": 2,
                "line_number": 15
            }
        }
    ]
}

Get Transaction Details

GET
/api/v1/entities/ {entity_id} /transactions/ {id}

Retrieve detailed information about a specific transaction.

Path Parameters
entity_id The unique identifier of the entity
id The unique identifier of the transaction

Response:

{
    "id": "t123e456-7890-4def-b123-456789abcdef",
    "statement_id": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
    "entity_id": "client123",
    "date": "2024-02-15",
    "description": "PAYMENT TO VENDOR XYZ",
    "amount": -1500.00,
    "currency": "USD",
    "category": "business_expense",
    "metadata": {
        "page_number": 2,
        "line_number": 15,
        "confidence_score": 0.95,
        "original_text": "VEN.XYZ PAYMENT        -1,500.00",
        "extracted_fields": {
            "vendor_name": "VENDOR XYZ",
            "transaction_type": "payment"
        }
    }
}

Error Handling

The API uses standard HTTP status codes and returns detailed error messages to help you debug issues.

Common Error Responses

Status Description
400 Bad Request Invalid input parameters
401 Unauthorized Missing or invalid authentication
402 Payment Required Insufficient credits
403 Forbidden Insufficient permissions
404 Not Found Resource not found
429 Too Many Requests Rate limit exceeded