Income Guide
Last updated Jun 7th, 2024
Overview
Income v2 is a mono service that helps a partner understand a customer’s income by analyzing their bank account transactions. The API analyses the money coming into a customer’s bank account so as to give you a clear picture of their income. The API also allows you to know how much a user earns, where their money is coming from, and how stable their income is over time.
It also helps you get a detailed look at their income by analyzing the bank transactions, providing you with insights into their earnings, their sources, and their consistency.
Integration Steps
Kindly note that there are two endpoints under under the Income API, these are:
- Initiate Income Request: Starts the process of analysing existing transactions in a connected bank account in the backgorund to generate income analysis report.
- Retrieve Income Details: Retrieves the generated income records linked to a particular account.
Initiate Income Request
This endpoint initiates the process of analysing all transactions in a connected bank account in the backgorund to generate income analysis report.
To initiate the endpoint, send a GET request to the following endpoint:
Request
GET https://api.withmono.com/v2/accounts/:id/income
Request Path Parameter
- id (required): This field expects the id of a connected bank account linked from mono connect
Request Query Parameter
- period (optional): This field expects an integer value expecting the number of months to consider. If period is not passed, then all transactions will be considered.
cURL Sample Request
Request
curl --request GET \
--url htthttps://api.withmono.com/v2/accounts/:id/income \
--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
{
"status": "successful",
"message": `The income of ${account.name} is 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 the Income v2 endpoint takes a bit of time to go through all your transactions in the background. Once the analysis is done, the detailed income report is sent to you via a webhook
Sample Webhook Response
Request
{
"event": "mono.events.account_income",
"data": {
"account": "66605869b806c997c5d21234",
"accountName": "SAMUEL OLAMIDE",
"accountNumber": "0129141234",
"income_summary": {
"total_income": 0,
"employer": ""
},
"income_streams": [
{
"income_type": "WAGES",
"frequency": "VARIABLE",
"monthly_average": 6532000,
"average_income_amount": 4450666.67,
"currency": "",
"stability": 0.16,
"first_income_date": "2023-07-25",
"last_income_date": "2024-05-13",
"last_income_amount": 3000000,
"last_income_description": "transfer from piggyvestpiggyvest paystack",
"periods_with_income": 5,
"number_of_incomes": 8,
"number_of_months": 5
},
{
"income_type": "WAGES",
"frequency": "MONTHLY",
"monthly_average": 100000,
"average_income_amount": 100000,
"currency": "",
"stability": 1,
"first_income_date": "2023-06-08",
"last_income_date": "2023-07-06",
"last_income_amount": 100000,
"last_income_description": "testfrm ",
"periods_with_income": 2,
"number_of_incomes": 2,
"number_of_months": 2
}
],
"income_source_type": "BANK",
"first_transaction_date": "2023-05-26",
"last_transaction_date": "2024-05-31",
"period": "12 months",
"number_of_income_streams": 2,
"monthly_average": 947428.57,
"monthly_average_regular": 50000,
"monthly_average_irregular": 1645500,
"total_regular_income_amount": 2,
"total_irregular_income_amount": 8,
"total_income": 600704393,
"annual_income": 600704393,
"monthly_income": 35335553,
}
}
With the above webhook mono.events.account_income received, you can proceed to call the income records endpoint to query the income insight report at a later time in the next section.
Income Response Description
Here's a table explaining each unique field in the response of the income record:
| Field | Description |
| status | Indicates the status of the API request, whether it was successful or failed. |
| message | Provides a message detailing the outcome of the API request. |
| timestamp | Specifies the timestamp of when the API response was generated. |
| account | The account id. |
| income summary | most recent income stream where income type is salary. |
| total_income | most recent amount received |
| employer | The entity or organization from which the income is received. |
| income_streams | An array containing details of each income stream, including type, frequency, average amount, stability, and more. |
| income_type | The type of income received i.e. SALARY or WAGES. |
| frequency | The frequency at which the income is received i.e. MONTHLY or VARIABLE. If the average number of days between the transactions in a stream is ≥ 20 and ≤ 35, then we consider it as monthly, else variable. |
| monthly_average | Total income in the stream/number of months |
| average_income_amount | Total income in the stream / total count of income |
| last_income_amount | Last amount received for the stream |
| currency | The currency in which the income is received. |
| stability | Variance of transaction amounts in the cluster. Ranges between 0-1 |
| last_income_description | Transaction narration for last transaction received for the stream |
| last_income_date | Date of last transaction received for the stream |
| periods_with_income | Number of months with income in stream |
| number_of_incomes | The total number of income events recorded. |
| income_source_type | The source of income (e.g., BANK). |
| first_transaction_date | Date of earliest transaction from all the income streams. Format YYYY-MM-DD |
| last_transaction_date | Date of latest transaction from all the income streams. Format YYYY-MM-DD |
| number_of_income_streams | Number of streams Credit transactions are grouped together based on their narration. Each group is called a stream. A stream should have a minimum of 2 transactions |
| monthly_average_regular | total monthly average from regular streams / total number of months from regular stream. Regular = stream.stability ≥ 0.6 |
| monthly_average_irregular | total monthly average from irregular streams / total number of months from irregular stream. Irregular = stream.stability < 0.6 |
| total_regular_income_amount | total average income amount for regular streams |
| total_irregular_income_amount | total average income amount for irregular streams |
| total_income | total monthly average from all streams |
| annual_income | total monthly average from all streams from the last 12 months. |
| monthly_income | total monthly average from all streams from the last 12 months/ total number of streams |
Explanatory Guide on Stability
What is Stability?
Stability measures the consistency of income amounts in a specific income stream. It ranges from 0 to 1, where:
- 0 means no consistency (highly variable income amounts).
- 1 means complete consistency (the income amount remains the same across transactions).
Stability evaluates consistency, not accuracy, so it does not verify the correctness of income but rather how predictable it is.
How is Stability Calculated?
The calculation involves analyzing the variance of transaction amounts within a stream. A lower variance indicates higher stability, while a higher variance results in lower stability. The metric provides insight into how consistent the income in a stream is.
How Stability Affects Calculations
Stability is factored into:
total_regular_income_amount: Includes streams where stability is ≥ 0.6 (considered regular).total_irregular_income_amount: Includes streams where stability is < 0.6 (considered irregular).
How Stability Ranges Impact Decisions
a. Stability ≥ 0.6: Indicates a "regular" income stream.
- Decision: Regular streams are considered reliable and can be factored into creditworthiness evaluations as stable income sources for loan repayment or credit limit determination.
b. Stability < 0.6: Indicates an "irregular" income stream.
- Decision: These streams may require additional scrutiny or be treated as secondary sources of income due to variability.
Stability helps differentiate between consistent, predictable income and fluctuating income, providing a clearer picture of financial reliability for decision-making.