📉Expenses

Our API provides flexible and powerful expense classification to support your financial assessments.

Expenses

POST {{baseUrl}}/bank-accounts/:bank_account_id/transaction-reports/expenses

Generate a summary report of expenses for a defined period of time.

API Request

Path Parameters

Name	Type	Description
bank_account_id*	String	The UUID for a Bank Account that gets generated and returned in the POST Create new Bank Account response.

Request Body

Name	Type	Description
start_date*	String	This field indicates the start date from which you would like to generate the summary report. In the following format: "yyyy-mm-dd"
end_date*	String	This field indicates the end date up until which you would like to generate the summary report. In the following format: "yyyy-mm-dd"

Status Codes

200 - OK

Multi Month

{
    "data": [
        {
            "id": "3b3eb594-7301-4e48-b681-76890e7517f0",
            "report": {
                "months": {
                    "year": 2024,
                    "month": "October",
                    "full_month": true,
                    "debits": "62872.36",
                    "number_of_debits": 60,
                    "other_expenses": "32276.49",
                    "number_of_other_expenses": 35,
                    "primary_expenses": "12378.42",
                    "number_of_primary_expenses": 19,
                    "recurring_expenses": "64.99",
                    "number_of_recurring_expenses": 1,
                    "obligation_expenses": "18152.46",
                    "number_of_obligation_expenses": 5  
                }
            },
            "startDate": "2024-10-01",
            "endDate": "2024-10-31",
            "type": "expenses"
        },
        {
            "id": "a212cfa1-b130-4588-b8d1-bfdba5426cab",
            "report": {
                "months": {
                    "year": 2024,
                    "month": "November",
                    "full_month": true,
                    "debits": "50368.50",
                    "number_of_debits": 52,
                    "other_expenses": "25557.98",
                    "number_of_other_expenses": 34,
                    "primary_expenses": "10993.07",
                    "number_of_primary_expenses": 13,
                    "recurring_expenses": "64.99",
                    "number_of_recurring_expenses": 1,
                    "obligation_expenses": "13752.46",
                    "number_of_obligation_expenses": 4
                }
            },
            "startDate": "2024-11-01",
            "endDate": "2024-11-30",
            "type": "expenses"
        }
    ]
}

No Transactions Available

{
    "data": [],
    "code": "no_transactions_found",
    "message": "No transactions found for {{bankaccountid}} of type summaryPlus"
}

400 - Bad Request

Inactive Online Session

{
    "data": "Online Banking Login Session has not been activated."
}

Incomplete Online Session

{
    "data": "Online Banking Login Session Incomplete."
}

Failed Online Session

{
    "data": "Online Banking Login Session Failed."
}

Expired Online Session

{
    "data": "Online Banking Login Session Link has expired."
}

Expense Categorisation

Expense data is derived from transaction data analysis, grouped into two levels of categorisation:

Default Expense Categorisation

Data Attribute	Description	Included Categories	Notes Logic
debits	All debit transactions found in the bank statement	debt, loans, expenses, fees, transfers	Captures all outgoing transactions regardless of type
primary_expenses	Not applicable in default categorisation	"null"	No separate distinction for essential or lifestyle expenses
obligation_expenses	Debt-related transactions	debt, loans	Used to assess financial commitments and liabilities
recurring_expenses	Not applicable in default categorisation	"null"	No logic for identifying recurring patterns
other_expenses	General spending and other outflows	transfers	Broadly captures all non-debt-related debits

Advanced Expense Categorisation

For richer insights, we recommend using our Transaction Categorisation Solution — a machine learning model that automatically refines each transaction into more granular categories.

🔗 Learn more about the Transaction Categorisation Solution

Data Attribute	Description	Advanced Categories	Notes / Logic
debits	All debit transactions found in the bank statement	All categories below	Full list of outgoing transactions
primary_expenses	Core, day-to-day living costs essential for survival and stability	accommodation, groceries_and_meals, investment_savings, mobile_prepaid, travel_expense, utilities, school_and_university_fees	Indicates basic affordability and lifestyle patterns
obligation_expenses	Fixed financial obligations and contract-based responsibilities	funeral_insurance, general_insurance, health_insurance, home_loan_finance, life_insurance, loan_repayments, mobile_contract, recurring_debit_order, vehicle_insurance, vehicle_loan_finance	Used for affordability and debt-to-income ratio calculations
recurring_expenses	Regularly occurring general expenses	recurring_general_expense	Captures stable, non-obligation recurring spend
other_expenses	Miscellaneous, lifestyle, or noisy spending that may not reflect core financial health	bank_fees, entertainment, failed_debit_order, failed_transaction, gambling, general_expense, other_expenses, transfers, withdrawal, unknown	Often excluded from affordability scoring but useful for behavioural profiling