Snapbooks logo Snapbooks Developer

Bank Statements API

The Bank Statements API enables you to fetch bank statements grouped by period and create new statements with transactions and balances. Each statement contains transaction counts, opening and closing balances, and reconciliation status indicators that are computed from the underlying transactions and balance records.

Endpoints

Method Endpoint Description
GET /bank-statements/by-period List bank statements grouped by period
POST /bank-statements Create a bank statement with transactions

Get Bank Statements by Period

GET /api/v2/bank-statements/by-period

Retrieves bank statements for a bank account grouped by a time interval (day, month, or year). The interval is auto-derived from the date range when not provided. Each statement covers one interval bucket within the requested range and aggregates the transactions and balances for that bucket.

Query Parameters

Parameter Type Required Description
bank_account_id integer Yes ID of the bank account
from_date date Yes Start date (YYYY-MM-DD)
to_date date No End date (YYYY-MM-DD). Defaults to today
interval string No Time interval for grouping. Auto-derived when omitted: day (≤31 days), month (≤366 days), year (>366 days). See Interval Values
with string No Comma-separated list of relations to include in the response. Supported: import_documents, transactions

Interval Values

Value Description
day Group transactions by day
month Group transactions by calendar month
year Group transactions by calendar year

Example Request

GET /api/v2/bank-statements/by-period?bank_account_id=123&from_date=2024-01-01&to_date=2024-03-31&interval=month&with=import_documents

Example Response

Returns a JSON array of statements, one per interval bucket. The example below shows two months and includes import_documents because it was requested via with.

[
  {
    "bank_account_id": 123,
    "period_start": "2024-01-01",
    "period_end": "2024-01-31",
    "period_start_balance": "10000.00",
    "period_end_balance": "12500.00",
    "total_transactions": 45,
    "reconciled_transactions": 42,
    "unreconciled_transactions": 3,
    "is_reconciled": false,
    "is_balanced": true,
    "import_documents": [
      {
        "id": 456,
        "document_type": "BankStatement",
        "document_date": "2024-01-31"
      }
    ]
  },
  {
    "bank_account_id": 123,
    "period_start": "2024-02-01",
    "period_end": "2024-02-29",
    "period_start_balance": "12500.00",
    "period_end_balance": "13750.00",
    "total_transactions": 38,
    "reconciled_transactions": 38,
    "unreconciled_transactions": 0,
    "is_reconciled": true,
    "is_balanced": true,
    "import_documents": []
  }
]

Error Responses

Status Description
400 Missing bank_account_id or from_date, from_date is after to_date, or invalid interval value
403 Bank account not found or no access to its client account

Create Bank Statement

POST /api/v2/bank-statements

Persists a bank statement together with its transactions. The transactions array is processed via the Bank Transactions serializer, so any field supported on BankTransaction is accepted on the embedded objects.

Request Body

Field Type Required Description
bank_account_id integer Yes ID of the bank account the statement belongs to
period_start date Yes Start date of the statement period
period_end date Yes End date of the statement period
period_start_balance decimal No Opening balance at the start of the period
period_end_balance decimal No Closing balance at the end of the period
transactions array No Bank transactions belonging to this statement. See Bank Transactions for the supported fields

Example Request

{
  "bank_account_id": 123,
  "period_start": "2024-01-01",
  "period_end": "2024-01-31",
  "period_start_balance": "10000.00",
  "period_end_balance": "12500.00",
  "transactions": [
    {
      "client_account_id": 7,
      "booking_date": "2024-01-15",
      "amount": "2500.00",
      "currency_code": "NOK",
      "memo": "Customer payment"
    }
  ]
}

Example Response (201 Created)

Returns the persisted statement object. Statement attributes such as total_transactions, is_reconciled, and is_balanced are computed from the saved transactions and balances.

{
  "bank_account_id": 123,
  "period_start": "2024-01-01",
  "period_end": "2024-01-31",
  "period_start_balance": "10000.00",
  "period_end_balance": "12500.00",
  "total_transactions": 1,
  "reconciled_transactions": 0,
  "unreconciled_transactions": 1,
  "is_reconciled": false,
  "is_balanced": true
}

Error Responses

Status Description
400 Missing request body, or invalid bank statement data
403 Bank account not found or no access to its client account

Statement Attributes

Attribute Type Description
bank_account_id integer ID of the bank account
period_start date Start date of the statement period
period_end date End date of the statement period
period_start_balance decimal Opening balance at the start of the period
period_end_balance decimal Closing balance at the end of the period
total_transactions integer Number of transactions in the period (read-only, computed)
reconciled_transactions integer Number of transactions whose external reconciled amount equals the transaction amount (read-only, computed)
unreconciled_transactions integer total_transactions − reconciled_transactions (read-only, computed)
is_reconciled boolean true when there is at least one transaction and every transaction is reconciled (read-only, computed)
is_balanced boolean true when period_start_balance + sum(transactions.amount) == period_end_balance, or when there are no transactions / balances are missing (read-only, computed)

Relations

Relation Description
import_documents Active BankStatement documents (PDF / CAMT / GBAT10 etc.) imported for the same bank account whose document period overlaps the statement period
transactions The bank transactions belonging to the statement (uses the Bank Transactions serializer)

Both relations are opt-in. Request them through with, e.g. ?with=import_documents,transactions.