Bank Connection
Beam provides comprehensive analytics on bank statement data pulled through the bank connection in the Connect process.
The connect process must be complete for these endpoints to return a successful response.
Account Summary
The account statement summary endpoint can be used to fetch account summary data about all accounts fetched for a connection.
Label Transactions
Beam provides a transaction labeling endpoint. Beam analysese (by default) multiple transaction attributes to infer the transaction label, or "spend category". Beam's labeling engine has been trained on a large corpus of South African bank statement transactions.
- Returns a list of categorised bank statement transaction labels - assigned to each label;
- This endpoint is available as both single-record and batch requests.
Affordability
The get_affordability endpoint calculates a consumer's verified monthly average affordability, or "discretionary income", as defined by the NCA.
As per the NCA, discretionary income is defined as:
"Gross Income less statutory deductions such as income tax, unemployment insurance fund contributions, maintenance payments, necessary expenses and less all other committed payment obligations disclosed by the consumer, including such as may appear from the consumer’s credit records held by the credit bureaux, which income is the amount available to fund the proposed credit instalment."
Beam has endeavoured to calculate customer affordability in line with the above definition, ensuring end-users remain compliant with respect to the NCR.
Example Response Body
{
"statusCode": 200,
"body": {
"monthly_affordability": [
{
"year": 2023,
"month": 4,
"primary_income": 83397.6,
"secondary_income": 5280.41,
"non_discretionary_expenses": -3604.88,
"discretionary_expenses": -76283.26,
"affordability_amount": 8789.87,
"beam_affordability": 1506.61,
"full_month": false
},
{
"year": 2023,
"month": 5,
"primary_income": 82361.58,
"secondary_income": 38351.45,
"non_discretionary_expenses": -32247.06,
"discretionary_expenses": -80107.89,
"affordability_amount": 88465.97,
"beam_affordability": 8358.08,
"full_month": true
}
],
"average_full_month_primary_income": 69306.11,
"average_full_month_secondary_income": 46793.96,
"average_full_month_non_discretionary_expenses": -23070.99,
"average_full_month_discretionary_expenses": -136295.24,
"average_full_month_affordability": -43266.16,
"average_full_month_beam_affordability": -52018.22
}
}
- primary_income: Aggregate amounts coming from primary income sources (e.g., Salaries & Wages).
- secondary_income: Aggregate amounts coming from non-primary sources (e.g., Bank Transfers).
- non_discretionary_expenses: Necessary expenses one cannot avoid and must pay on a regular basis to maintain a basic standard of living (e.g., utilities).
- discretionary_expenses: Optional expenses for goods and services that are not essential (e.g., nightlife & entertainment).
- affordability_amount: Primary income + secondary income – non-discretionary expenses.
This is a measure of “discretionary income” in line with the NCA, reflecting the amount available after mandatory expenses. - beam_affordability: Primary income + secondary income – non-discretionary expenses – discretionary expenses.
This goes a step further and subtracts all tracked expenses (both non-discretionary and discretionary). The result is a more stringent “net leftover” measure. - full_month: Boolean indicating whether the data for that month covers the entire month (i.e., from the 1st to the last day), based on the dates provided in the request.
Income Analysis
The get_income_analysis endpoint provides a detailed analysis on Primary Income lines (ie Salaries and Wages). This analysis primarily comprises of three metrics:
Example response body:
{
"bank_connection": "66b9e5f46b1646ce983e767c",
"income_analysis": {
"consistency_score": 0.6,
"longevity_score": 0.6,
"regularity_score": 0.6,
"income_month_breaks": 0.6,
"income_indicator": 0.6,
"months_back": 0.6,
"income_heatmap": {
"1": 0.6226091983885061,
"2": 0.6566979036690341,
"3": 0.6908305188318503,
"4": 0.725007043876948,
"5": 0.7592274788043323,
"6": 0.7934918236140031,
"7": 0.8278000783059554,
"8": 0.8621522428801923,
"9": 0.8965483173367179,
"10": 0.9309883016755265,
"11": 0.9654721958966198,
"12": 1.0,
"13": 0.0,
"14": 0.03327637245825698,
"15": 0.06659665479880061,
"16": 0.0999608470216291,
"17": 0.1333689491267407,
"18": 0.1668209611141407,
"19": 0.20031688298382197,
"20": 0.23385671473578815,
"21": 0.26744045637004277,
"22": 0.3010681078865804,
"23": 0.33473966928540116,
"24": 0.36845514056651035,
"25": 0.40221452172990263,
"26": 0.436017812775578,
"27": 0.4698650137035419,
"28": 0.5037561245137887,
"29": 0.5376911452063204,
"30": 0.5432171373617541,
"31": 0.5422054992945656
},
"strike_date": 12.0
}
}
consistency_score: Measures how stable the salary amount is. More variable month-over-month salary amounts reduce this score.longevity_score: Measures the time period in which the customer's primary income has been detected. A longer history of salary lines being detected improves this score.regularity_score: Measures income "strike" date regularity. More variation in the day of month the salary being received reduces this score.misc_info: More granular income metadata.income_month_breaks- number of breaks in income detected.income_indicator- periodicity of income: monthly, bi-weekly, weekly or irregular (for when no discernable pattern is detected).months_back- total income history length, measured in months.
income_heatmap: A 'day-of-month' distribution of all inflows into the user's bank account, averaged over the entire statement history.strike_date: Recommended strike date for debiting the customer's account, defined as the day of the month where the most income was received, on average.
Risk Insights
This series of endpoints provide behavioural insights into a customer's spending habits. The Risk Insights series comprises of:
Gambling
The Gambling insight provides standardized metrics into all gambling transactions. For months with both salary lines and gambling lines, the function returns:
- year - calendar year
- month - calendar month
- total_gambling_amount - total amount of gambling spend for that month
- total_salary_amount - total salary for the month (if available)
- gambling_proportion - gambling spend as a proportion of salary
Additional fields:
- monthly_average_gambling_spend - average gambling spend across all months
- monthly_average_gambling_proportion - average ratio of gambling spend to salary across all months
Overdraft Usage
The Overdraft insight calculates a client's use of their bank overdraft. Specifically, this endpoint calculates:
- The number of days within each calendar month that the balance is less than 0 (i.e., in overdraft)
total_days_in_overdraft- total days in overdraft over the entire observation periodtotal_proportion_of_days_in_overdraft- proportion of overdraft days relative to the total days in the observation periodunique_months- number of unique months in the observation periodmonthly_average_days_in_overdraft- average days in overdraft per month, over the entire observation period
Returned Debit Orders
This endpoint returns metrics on a customer's predicted number of returned (bounced) debit orders. Specifically:
last_month_count- predicted count of returned debit orders in the past monthlast_3_months_count- predicted count of returned debit orders in the past 3 monthslast_6_months_count- predicted count of returned debit orders in the past 6 monthslast_12_months_count- predicted count of returned debit orders in the past 12 monthsmonthly_average_debit_order_value- average (absolute) monetary value of returned debit orders per month
ATM & Cash Withdrawals
This insight returns standardized metrics around a user's ATM and Cash withdrawal behavior. Specifically, this endpoint returns:
- monthly_atm_and_cash_spend_analysis – an array of monthly metrics, including:
year- calendar yearmonth- calendar monthtotal_withdrawal_amount- total ATM/cash withdrawal amount for the monthtotal_salary_amount- total salary amount for the month (if available)cash_proportion- ratio of monthly ATM/cash withdrawals to salary (if available)
atm_and_cash_average_amount- average monthly ATM/cash withdrawal amount across all monthsaverage_withdrawal_proportion- average ratio of ATM/cash withdrawals to salary across all months
Net Saver or Spender
This insight tracks the customer's aggregated balances across all accounts and returns whether the trend shows a net increase (saver) or decrease (spender) in balance. It does this by calculating the slope of the line of best fit through the aggregate balance history:
- Returns
"Net Saver"or"Net Spender"depending on whether the gradient of the line of best fit through the aggregated balances is positive or negative.
Social Security Insights
This insight tracks any Social Security (SS), pension, or UIF payments being made into the account. These payments may indicate unemployment, retirement, or similar financial circumstances. The endpoint returns:
monthly_ssi_analysis- array of monthly inflows, including:yearmonthtotal_social_security_amount- sum of social security/pension/UIF payments (absolute amounts)total_payments- number of individual social security transactions that month
monthly_average_ssi- average amount of social security inflows across all monthsmonthly_count_ssi- average count of social security inflow transactions across all months
Short-Term High-Cost Lender Relationships
The Short-Term High-Cost Lender insight identifies transactions labeled as “Short-Term, High Cost Loan Repayment.” These typically refer to payday lenders or microlenders offering short-term, high-interest loans. Specifically, this endpoint returns:
sthclr_analysis- array of monthly metrics, including:yearmonthtotal_sthclr_amount- total short-term lender repayment amount (absolute) for that monthtotal_salary_amount- total salary amount for the month (if applicable)sthclr_proportion- ratio of the short-term lender repayments to the monthly salary
monthly_average_sthclr- average short-term lender repayment across all monthsmonthly_average_sthclr_proportion- average ratio of short-term lender repayment to salary
Loan Repayments
The Loan Repayments insight identifies all standard loan or debt account repayments (e.g., home loans, auto loans, general loans). Specifically, it returns:
loan_repayments_analysis- array of monthly metrics, including:yearmonthtotal_loan_repayment_amount- total loan repayment amount (absolute) for that monthtotal_salary_amount- total salary amount for the month (if applicable)loan_repayment_proportion- ratio of loan repayments to the monthly salary
monthly_average_loan_repayments- average monthly loan repayment amount across all monthsmonthly_average_loan_repayments_proportion- average ratio of loan repayments to salary
Debt Review
The Debt Review insight identifies all payments flagged as “Debt Review Payment,” indicating the consumer is under a debt review program. Specifically, it returns:
debt_review_analysis- array of monthly metrics, including:yearmonthtotal_debt_review_amount- total debt review payment amount (absolute) for that monthtotal_salary_amount- total salary amount for the month (if applicable)debt_review_proportion- ratio of debt review payments to the monthly salary
monthly_average_debt_review- average monthly amount spent on debt review payments across all monthsmonthly_average_debt_review_proportion- average ratio of debt review payments to salary
Example Updated Response Body for Risk Insights
Below is an example response body showing all the Risk Insights sub-endpoints under a single risk_insights object. You would see similar keys/structures in each sub-insight block, adapted to the specific data:
{
"statusCode": 200,
"body": {
"begin_date": "2023-04-21",
"end_date": "2023-10-16",
"risk_insights": {
"gambling_insights": {
"monthly_gambling_analysis": [
{
"year": 2023,
"month": 4,
"total_gambling_amount": 0.0,
"total_salary_amount": 83397.6,
"gambling_proportion": 0.0
},
{
"year": 2023,
"month": 5,
"total_gambling_amount": 1574.08,
"total_salary_amount": 82361.58,
"gambling_proportion": 0.0191
}
],
"monthly_average_gambling_spend": 606.7,
"monthly_average_gambling_proportion": 0.00949
},
"overdraft_insights": {
"monthly_overdraft_analysis": [
{ "year": 2023, "month": 4, "days_in_overdraft": 0 },
{ "year": 2023, "month": 5, "days_in_overdraft": 0 }
],
"total_days_in_overdraft": 4,
"total_proportion_of_days_in_overdraft": 0.0223,
"unique_months": 7,
"monthly_average_days_in_overdraft": 0.57
},
"returned_debit_orders_insights": {
"last_month_count": 1,
"last_3_months_count": 3,
"last_6_months_count": 5,
"last_12_months_count": 5,
"monthly_average_debit_order_value": 58.38
},
"atm_and_cash_insights": {
"monthly_atm_and_cash_spend_analysis": [
{
"year": 2023,
"month": 5,
"total_withdrawal_amount": 1295.39,
"total_salary_amount": 82361.58,
"cash_proportion": 0.0157
}
],
"atm_and_cash_average_amount": 367.41,
"average_withdrawal_proportion": 0.00514
},
"net_saver_spender_insights": {
"net_saver_spender": "Net Spender"
},
"ssi_insights": {
"monthly_ssi_analysis": [
{
"year": 2023,
"month": 9,
"total_social_security_amount": 0.0,
"total_payments": 0.0
}
],
"monthly_average_ssi": 0,
"monthly_count_ssi": 0
},
"sthclr_insights": {
"sthclr_analysis": [
{
"year": 2023,
"month": 5,
"total_sthclr_amount": 300.0,
"total_salary_amount": 82361.58,
"sthclr_proportion": 0.00364
}
],
"monthly_average_sthclr": 150.0,
"monthly_average_sthclr_proportion": 0.0016
},
"loan_repayments_insights": {
"loan_repayments_analysis": [
{
"year": 2023,
"month": 4,
"total_loan_repayment_amount": 5100.65,
"total_salary_amount": 68985.51,
"loan_repayment_proportion": 0.0739
}
],
"monthly_average_loan_repayments": 4325.42,
"monthly_average_loan_repayments_proportion": 0.054
},
"debt_review_insights": {
"debt_review_analysis": [
{
"year": 2023,
"month": 6,
"total_debt_review_amount": 250.0,
"total_salary_amount": 41340.79,
"debt_review_proportion": 0.0060
}
],
"monthly_average_debt_review": 250.0,
"monthly_average_debt_review_proportion": 0.0060
}
}
}
}
Liquidity Score
The Liquidity Score predicts how cashflow positive an individual's bank account will remain in the future. This is quantified as the likelihood an individual will remain above R0 across all bank accounts over the defined term.
Specifically, this calculates the likelihood an individual's aggregate account balance will remain above R0 over the next:
- 30,
- 60,
- 90 days
After accounting for future balance forecasts, as well as accounting for prior balance history and statistical shocks.
Example response body:
{
"bank_connection": "66b9e5f46b1646ce983e767c",
"liquidity_score": {
"start_date": "2023-08-13",
"end_date": "2024-08-12",
"field_30_day_liquidity_score": 100.0,
"field_60_day_liquidity_score": 100.0,
"field_90_day_liquidity_score": 100.0,
"balance_forecast": [
{
"date": "2024-08-13",
"balance": 1365174.0
},
{
"date": "2024-08-14",
"balance": 1371509.19
},
{
"date": "2024-08-15",
"balance": 1373937.21
},
{
"date": "2024-08-16",
"balance": 1376301.65
},
{
"date": "2024-08-17",
"balance": 1378622.65
},
{
"date": "2024-08-18",
"balance": 1380921.55
},
{
"date": "2024-08-19",
"balance": 1383217.67
},
{
"date": "2024-08-20",
"balance": 1385525.7
},
{
"date": "2024-08-21",
"balance": 1387854.13
},
{
"date": "2024-08-22",
"balance": 1390205.03
},
{
"date": "2024-08-23",
"balance": 1392575.01
},
{
"date": "2024-08-24",
"balance": 1394957.17
},
{
"date": "2024-08-25",
"balance": 1397343.39
},
{
"date": "2024-08-26",
"balance": 1399726.56
},
{
"date": "2024-08-27",
"balance": 1402102.22
},
{
"date": "2024-08-28",
"balance": 1404469.33
},
{
"date": "2024-08-29",
"balance": 1406830.05
},
{
"date": "2024-08-30",
"balance": 1409188.84
},
{
"date": "2024-08-31",
"balance": 1411550.98
},
{
"date": "2024-09-01",
"balance": 1413921.1
},
{
"date": "2024-09-02",
"balance": 1416302.01
},
{
"date": "2024-09-03",
"balance": 1418694.15
},
{
"date": "2024-09-04",
"balance": 1421095.66
},
{
"date": "2024-09-05",
"balance": 1423503.1
},
{
"date": "2024-09-06",
"balance": 1425912.51
},
{
"date": "2024-09-07",
"balance": 1428320.52
},
{
"date": "2024-09-08",
"balance": 1430725.2
},
{
"date": "2024-09-09",
"balance": 1433126.53
},
{
"date": "2024-09-10",
"balance": 1435526.22
},
{
"date": "2024-09-11",
"balance": 1437927.16
},
{
"date": "2024-09-12",
"balance": 1440332.55
},
{
"date": "2024-09-13",
"balance": 1442744.98
},
{
"date": "2024-09-14",
"balance": 1445165.8
},
{
"date": "2024-09-15",
"balance": 1447594.75
},
{
"date": "2024-09-16",
"balance": 1450030.18
},
{
"date": "2024-09-17",
"balance": 1452469.57
},
{
"date": "2024-09-18",
"balance": 1454910.22
},
{
"date": "2024-09-19",
"balance": 1457350.08
},
{
"date": "2024-09-20",
"balance": 1459788.24
},
{
"date": "2024-09-21",
"balance": 1462225.13
},
{
"date": "2024-09-22",
"balance": 1464662.37
},
{
"date": "2024-09-23",
"balance": 1467102.24
},
{
"date": "2024-09-24",
"balance": 1469547.06
},
{
"date": "2024-09-25",
"balance": 1471998.47
},
{
"date": "2024-09-26",
"balance": 1474457.09
},
{
"date": "2024-09-27",
"balance": 1476922.3
},
{
"date": "2024-09-28",
"balance": 1479392.52
},
{
"date": "2024-09-29",
"balance": 1481865.63
},
{
"date": "2024-09-30",
"balance": 1484339.65
},
{
"date": "2024-10-01",
"balance": 1486813.22
},
{
"date": "2024-10-02",
"balance": 1489286.0
},
{
"date": "2024-10-03",
"balance": 1491758.73
},
{
"date": "2024-10-04",
"balance": 1494232.97
},
{
"date": "2024-10-05",
"balance": 1496710.68
},
{
"date": "2024-10-06",
"balance": 1499193.63
},
{
"date": "2024-10-07",
"balance": 1501682.9
},
{
"date": "2024-10-08",
"balance": 1504178.62
},
{
"date": "2024-10-09",
"balance": 1506679.94
},
{
"date": "2024-10-10",
"balance": 1509185.3
},
{
"date": "2024-10-11",
"balance": 1511692.87
},
{
"date": "2024-10-12",
"balance": 1514201.09
},
{
"date": "2024-10-13",
"balance": 1516709.1
},
{
"date": "2024-10-14",
"balance": 1519216.95
},
{
"date": "2024-10-15",
"balance": 1521725.6
},
{
"date": "2024-10-16",
"balance": 1524236.6
},
{
"date": "2024-10-17",
"balance": 1526751.66
},
{
"date": "2024-10-18",
"balance": 1529272.18
},
{
"date": "2024-10-19",
"balance": 1531798.81
},
{
"date": "2024-10-20",
"balance": 1534331.33
},
{
"date": "2024-10-21",
"balance": 1536868.71
},
{
"date": "2024-10-22",
"balance": 1539409.38
},
{
"date": "2024-10-23",
"balance": 1541951.74
},
{
"date": "2024-10-24",
"balance": 1544494.55
},
{
"date": "2024-10-25",
"balance": 1547037.34
},
{
"date": "2024-10-26",
"balance": 1549580.47
},
{
"date": "2024-10-27",
"balance": 1552125.08
},
{
"date": "2024-10-28",
"balance": 1554672.72
},
{
"date": "2024-10-29",
"balance": 1557224.91
},
{
"date": "2024-10-30",
"balance": 1559782.72
},
{
"date": "2024-10-31",
"balance": 1562346.48
},
{
"date": "2024-11-01",
"balance": 1564915.66
},
{
"date": "2024-11-02",
"balance": 1567489.06
},
{
"date": "2024-11-03",
"balance": 1570065.12
},
{
"date": "2024-11-04",
"balance": 1572642.42
},
{
"date": "2024-11-05",
"balance": 1575220.01
},
{
"date": "2024-11-06",
"balance": 1577797.73
},
{
"date": "2024-11-07",
"balance": 1580376.24
},
{
"date": "2024-11-08",
"balance": 1582956.84
},
{
"date": "2024-11-09",
"balance": 1585541.07
},
{
"date": "2024-11-10",
"balance": 1588130.28
}
]
}
}
balance_forecast: returns daily aggregate balance predictions for 90 days in the future, starting from the application date.
Expense Analysis
The Expense Analysis endpoint provides a detailed breakdown of an individual's expenses. The endpoint returns the aggregate - as well as proportionate - amount spent on each expense category over the analysis period, ordered from largest to smallest category.
Finally, the endpoint returns the split of discretionary vs non-discretionary expenses over the analysis window, with a count of unique months analysed.
Example response body:
{
"bank_connection": "66c5f3eb4e7cecced7i82fe4",
"expenses_insights": {
"top_expense_amounts": [
{
"label": "Subscriptions",
"amount": 32984.48,
"average_monthly_spend": 4712.07,
"percentage_of_total_spend": 28.81
},
{
"label": "Eating Out",
"amount": 25224.67,
"average_monthly_spend": 3603.52,
"percentage_of_total_spend": 22.03
},
{
"label": "Online Purchase",
"amount": 12110.57,
"average_monthly_spend": 1730.08,
"percentage_of_total_spend": 10.58
},
{
"label": "Fuel",
"amount": 8600.28,
"average_monthly_spend": 1228.61,
"percentage_of_total_spend": 7.51
},
{
"label": "Groceries",
"amount": 5216.45,
"average_monthly_spend": 745.21,
"percentage_of_total_spend": 4.56
},
{
"label": "Bank Transfer Out",
"amount": 3975.22,
"average_monthly_spend": 567.89,
"percentage_of_total_spend": 3.47
},
{
"label": "Nightlife & Entertainment",
"amount": 3816.93,
"average_monthly_spend": 545.28,
"percentage_of_total_spend": 3.33
},
{
"label": "Coffee",
"amount": 3764.0,
"average_monthly_spend": 537.71,
"percentage_of_total_spend": 3.29
},
{
"label": "Home and Garden",
"amount": 3187.74,
"average_monthly_spend": 455.39,
"percentage_of_total_spend": 2.78
},
{
"label": "Ride Sharing",
"amount": 3012.84,
"average_monthly_spend": 430.41,
"percentage_of_total_spend": 2.63
},
{
"label": "General Purchases",
"amount": 2606.6,
"average_monthly_spend": 372.37,
"percentage_of_total_spend": 2.28
},
{
"label": "Health and Medical",
"amount": 2495.57,
"average_monthly_spend": 356.51,
"percentage_of_total_spend": 2.18
},
{
"label": "Personal Care",
"amount": 2488.36,
"average_monthly_spend": 355.48,
"percentage_of_total_spend": 2.17
},
{
"label": "Clothing",
"amount": 2472.77,
"average_monthly_spend": 353.25,
"percentage_of_total_spend": 2.16
},
{
"label": "Sport",
"amount": 1474.68,
"average_monthly_spend": 210.67,
"percentage_of_total_spend": 1.29
},
{
"label": "Transport",
"amount": 374.08,
"average_monthly_spend": 53.44,
"percentage_of_total_spend": 0.33
},
{
"label": "Prepaid Data Purchase",
"amount": 250.0,
"average_monthly_spend": 35.71,
"percentage_of_total_spend": 0.22
},
{
"label": "Electronics and Appliances",
"amount": 188.51,
"average_monthly_spend": 26.93,
"percentage_of_total_spend": 0.16
},
{
"label": "Bank Charges and Fees",
"amount": 186.19,
"average_monthly_spend": 26.6,
"percentage_of_total_spend": 0.16
},
{
"label": "Parking",
"amount": 42.0,
"average_monthly_spend": 6.0,
"percentage_of_total_spend": 0.04
},
{
"label": "Gambling",
"amount": 20.0,
"average_monthly_spend": 2.86,
"percentage_of_total_spend": 0.02
},
{
"label": "Insufficient Funds Fee",
"amount": 8.5,
"average_monthly_spend": 1.21,
"percentage_of_total_spend": 0.01
},
{
"label": "Uncategorised",
"amount": 8.5,
"average_monthly_spend": 1.21,
"percentage_of_total_spend": 0.01
}
],
"unique_months": 7,
"spend_split": {
"discretionary_spend_percentage": 95.27,
"non_discretionary_spend_percentage": 4.73
}
}
}