Statement Insights Guide
Last updated Jun 7th, 2024
Overview
The Statement Insights API analyzes transactions linked to a provided account ID and returns insights based on the transaction data. These insights offer valuable information for understanding spending patterns, financial habits, and overall account activity.
Integration Steps
Kindly note that there are two endpoints under under the Statement Insight API, these are:
- Initiate Statement Insights: Starts the process of analyzing transactions and returns insights based on the provided account ID.
- Retrieve Statement Insights Records: Retrieves the generated insight records linked to a particular account.
1
Initiate Statement Insights
This endpoint triggers and starts the process of analysing all transactions that are already linked to a connected bank account.
To initiate the endpoint, send a GET request to the following endpoint:
Request
1
GET https://api.withmono.com/v1/enrichments/:id/statement-insights
Request Path Parameter
- id (required): This field expects the id of a connected bank account linked from mono connect
cURL Sample Request
Request
1234
curl --request GET \
--url https://api.withmono.com/v1/enrichments/:id/statement-insights \
--header 'mono-sec-key: string' \
--header 'accept: application/json'
Request Headers
Include the following header in your request for authentication:
mono-sec-key(required): Your Mono secret key.
Success Response
If the initiation request is successful, you will receive the following API response:
Request
1234567
{
"status": "successful",
"message": "Statement insights are currently being processed, and
the data will be sent to you through your webhook",
"timestamp": "2024-05-21T10:38:02.376Z",
"data": null
}
Please note that once the API request above is successful, our system generates an insight report and sends you a webhook notification confirming completion.
Sample Webhook Response
Request
123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106
{
"event": "mono.events.statement_insights",
"data": {
"start_date": "2022-08-19T12:39:00.100Z",
"end_date": "2023-06-15T09:14:00.200Z",
"transaction_length": 299, //number of days between first and last transaction
"transaction_count": 99,
"balance_after_expense": 1632304,
"account_summary": {
"opening_balance": 157998.02,
"closing_balance": 61710.65,
"average_balance": 100810.21,
"debit_to_credit_ratio": "1.2:1",
"overall_credits": 494267.22,
"overall_debits": 593554.59,
"number_of_credit_transactions": 25,
"number_of_debit_transactions": 73,
"total_recurring_credits": 437589.00,
"total_recurring_debits": 120000.00
},
"activity_insights": { //activity_insights
"rare_findings": {
"immediate_large_withdrawal_post_payday": "Not Detected", // more than 2 occurances of
withdrawal >80% of salary within 24hrs of credit.
"identical_debit_vs_credit": "Not Detected",
"cash_deposits_larger_than_salary": "Not Detected",
}
},
"transaction_details": {
"highest_debits": [
{"amount": 30000.00, "date": "2021-04-17"},
{"amount": 30000.00, "date": "2021-06-04"},
{"amount": 21320.00, "date": "2021-01-07"}
],
"highest_credits": [
{"amount": 48621.00, "date": "2021-01-01"},
{"amount": 48621.00, "date": "2021-02-02"},
{"amount": 48621.00, "date": "2021-03-01"}
]
},
"inflow": {
"all_transaction": {
"average_per_month": {
"last_12_months": 630270.67,
"since_first_transaction": 6263456.17
},
"monthly_sum": [934, 100000, 37800]
},
"repeat_transactions": {
"average_per_month": {
"last_12_months": 0,
"since_first_transaction": 7000000
},
"monthly_sum": []
}
},
"outflow": {
"all_transaction": {
"average_per_month": {
"last_12_months": 114069.67,
"since_first_transaction": 1743106.6
},
"monthly_sum": [75, 75, 93, 50000]
},
"repeat_transactions": {
"average_per_month": {
"last_12_months": 82130.42,
"since_first_transaction": 1184950.7
},
"monthly_sum": [120000, 150, 50000]
}
},
"recurring_transactions": [
{
"description": "transfer from piggyvest paystack",
"category": "transfer",
"type": "credit",
"count": 2,
"stability": 0.82,
"consistency": 0.57,
"average_monthly_sum": 3500000,
"average_days_between_transactions": 25,
"compound_monthly_growth_rate": -0.6,
"monthly_growth_rate": [
{"total": 5000000, "growth_rate": 0, "month": "2022-12"},
{"total": 2000000, "growth_rate": -0.6, "month": "2023-01"}
]
},
{
"description": "transfer from piggyvest paystack",
"category": "betting",
"type": "debit",
"count": 2,
"stability": 0.82,
"consistency": 0.57,
"average_monthly_sum": 3500000,
"average_days_between_transactions": 25,
"compound_monthly_growth_rate": -0.6,
"monthly_growth_rate": [
{"total": 5000000, "growth_rate": 0, "month": "2022-12"},
{"total": 2000000, "growth_rate": -0.6, "month": "2023-01"}
]
}
]
}
}
With the above webhook mono.events.statement_insights received, you can proceed to call the insights records endpoint to query the statement insight report at a later time in the next section.
Here's a table explaining each unique field in the response of the statement insights:
| Field | Description |
| account | The is the account id |
| start_date | Date of earliest transaction linked the account. Format YYYY-MM-DD |
| end_date | Date of latest transaction linked the account. Format YYYY-MM-DD |
| transaction_length | Number of days between first and last transaction |
| transaction_count | Number of transactions found linked to the account |
| balance_after_expense | Total credit amount - total debit amount of all transactions |
| account_summary | Account summary breakdown |
| opening_balance | transaction.balance of earliest transaction |
| closing_balance | transaction.balance of latest transaction |
| average_balance | Average of transaction.balance for all transactions |
| debit_to_credit_ratio | Ratio of all debits to credit |
| overall_credits | Total of all credit amounts |
| overall_debits | Total of all debits amounts |
| number_of_credit_transactions | Number of all credit transactions |
| number_of_debit_transactions | Number of all debit transactions |
| total_recurring_credits | Total amount for all recurring credit transactions |
| total_recurring_debits | Total amount for all recurring debit transactions |
| activity_insights | A breakdow of the activity insights |
| rare_findings | This is the rare findings breakdown |
| immediate_large_withdrawal_post_payday | More than 2 occurrences of withdrawal >80% of salary within 24hrs of credit. |
| identical_debit_vs_credit | Finds a match for the following criteria's; 1. Same credit and debit amounts; 2. Both credit and debit are transfers; 3. Debit happened within 3 days after credit |
| cash_deposits_larger_than_salary | If salary is found; Credit amount higher than the salary amount. |
| transaction_details[] | A breakdown of the transaction details information |
| highest_debits | Top 3 highest debits. We return the amount and date of transaction |
| highest_credits | Top 3 highest credit. We return the amount and date of transaction |
| inflow | Considers credit transactions |
| outflow | Considers debit transactions |
| all_transaction | all_transaction: This section considers all transactions, whether they are repeated or not; average_per_month: average per month; monthly_sum: sum of all amounts for each month for the last 12 months |
| repeat_transactions | This section considers repeated transactions |
| recurring_transactions | This returns the clusters of repeat transactions and its details |
| description | This is the transaction description for that cluster. The version returned maybe a modified version that has been stripped some text like months and reference number. |
| category | Cluster category returned from out categoriser |
| type | The type of transactions in the cluster. This can be credit or debit |
| count | Total number of transactions in the cluster |
| stability | Variance of transaction amounts in the cluster. Ranges between 0-1 |
| consistency | Consistency of the transaction amounts in the cluster, weighted by days between transactions. Ranges between 0-1 |
| average_monthly_sum | Total monthly average / Number of months |
| average_days_between_transactions | Average number of days between transactions in the cluster |
| compound_monthly_growth_rate | Compound monthly growth rate for that cluster |
| monthly_growth_rate | monthly_growth_rate: monthly growth rate in total transaction amount for that cluster ;total: total for specific month; growth_rate: increase in total in relation to previous month; month: month being considered |