Verify income

Learn how to verify a user income

Overview

Okra’s Income API calculates an end user’s income using real-time financial transactions from their bank accounts.

Whether it’s day laborer earnings, salary, and pension, or an uncle who provides monthly aid, Okra makes it easy to understand all the structured and unstructured sources of income of your customer.
Income provides a wealth of opportunity in KYC validation.

Understanding a user’s current and past earning history over a 3 to 24 month period can unlock critical eligibility information like employment verification, spending patterns, and power. These can all be used to unlock vital eligibility use cases like disbursement amounts, product recommendations, payment tenures, and more.

How It works

Once an end-user grants Okra permission to access a bank account, Okra services pull transactions and send them to the Okra NLU system. At the NLU, income-related features such as Named Entities, Transaction frequency, and transaction date are extracted.

In this guide, we'll walk through from scratch, how to use the Income Verification API when building Income-based Fintech products.

Explanation

The NLU system produces income features such as:

  • Named Entities: Named Entities are special keywords and sub-texts that have been identified in the transaction description. These include transaction benefactor, utility keywords, the reason for transaction, nuban and income related keywords.
  • Transaction Group: Transactions can belong to any of the five categories: VAT, Commissions, ATM/POS, Transfer, and reversals. Income stream transactions are generally expected to be in the “transfer” category/group.
  • Transaction Frequency: This is the rate of reoccurrence of a certain kind of transaction. Similar transactions are grouped together by frequency.

The income engine uses the features to accurately identify a transaction as belonging to an income stream. Income is broadly classified into three categories:

Salary

Salaries are sums of money paid into a user’s account by a registered Nigerian company. Salary-related keywords and named entities that belong to registered Nigerian companies are strong indications of salary-related transactions. The monthly numeric credit inflow is then processed as income.

Recurrent credit

These are fixed sums of money that are periodically credited to a user's account. These are usually passive returns from investments and businesses or a steady inflow from a third-party sender. They can occur monthly, quarterly, or yearly.

Unstructured income

This type of income usually exists for people who do not have a fixed amount of recurring inflow. The market structure in Nigeria accounts for this type of income. Small business owners such as butchers, cobblers, and SME proprietors usually belong to this category.

A key feature in the salary and recurrent credit income types of income is next_pay_date. This estimates the next date that the salary/recurrent credit is expected to be paid in the account.

The income object also comes with a projected sum which estimates how much a user is expected to make by the end of the calendar year.

Evaluating income model

The income product is evaluated using a confidence score. The confidence score is a measure of how accurately a transaction data is (was) classified as income. It also, by extension, indicates the correctness of the projected income sum.

As with every machine learning model, accuracy, recall, and precision are used to evaluate the performance of the system by deriving values from a confusion matrix.

TP: True positive: Number of income (stream) transactions accurately classified as income transactions (stream)

FN: False Negative: Number of actual Income (stream) transactions misclassified as non-income (stream) transactions

FP: False Positive: Number of non-income transactions misclassified as income (stream) transactions

TN: True Negative: Number of non-income transactions correctly identified as non-income transactions.

Our confidence score is the total number of correctly classified transactions (income and non-income) expressed as a percentage.

Confidence Score = (TP + TN) / (TP + TN + FP + FN) * 100

Income model

Before diving deep into the tutorial, you might need to get yourself familiar with the Income object models.

Field

Description

id
ObjectID

Unique Auth ID (Unique Okra Identifier)

last_year_income
Number

Total income value from the previous year

ledger_balance
Number

The closing balance of the account

account
ObjectID

Unique Account ID (Unique Okra Identifier)

connected
Boolean

Customer connection status (Did they choose to connect this account to you?)

customer
ObjectID

Unique Customer ID (Unique Okra Identifier)

See Manage Customers ]

record
ObjectID

Unique Record ID (Unique Okra Identifier)

See Records

owner
ObjectID

Unique Company ID (Unique Okra Identifier) (Your Client Token)

env
String

Okra API Env the Auth was pulled from production or production-sandbox

created_at
Date

Date of Authentication

last_updated
Object

Last Date of Authentication

curl -X POST https://api.okra.ng/v2/products/income/process
-H 'Content-Type: application/json' 
-H 'Authorization: Bearer <secretKey>'
-d '{customer_id: xxxxxxxxxxxxx}'
{
        "income": {
        "confidence": "98.9%",
                "current_year": 2022,
        "last_two_years_income": 224616.0,
        "last_two_years_to_this_year_projected_income": 21728473.17,
        "last_year_income": 11726584.8,
        "last_year_to_this_year_projected_income": 32480401.75,
        "number_of_income_streams": 2,
        "projected_yearly_income": 53234218.7,
        "streams": [
            {
                "account": "xxxxx-xxxxx-xxxxx-xxxxxx",
                "avg_monthly_income": 194693.75,
                "bank": "xxxx-xxxxx-xxxxxx-xxxxxx",
                "days": 89,
                "income_last_date": "Wed, 05 May 2021 00:00:00 GMT",
                "income_start_date": "Fri, 01 Jan 2021 00:00:00 GMT",
                "monthly_income": 194693.75,
                "number_of_months": 4,
                "projected_months": 10.0,
                "employer": "CrossWallet, Inc",
                "type": "salary"
            },
            {
                "account": "xxxx-xxxx-xxxxx-xxxxx-xxxxx",
                "avg_monthly_income": 4273940.1,
                "bank": "xxxx-xxxxx-xxxx-xxx-xxxxx",
                "days": 104,
                "monthly_income": 4273940.1,
                "number_of_months": 5,
                "projected_months": 12.0,
                "type": "unstructured"
            }
        ]
    }
{
      "method":"INCOME",
      "callback_type":"INCOME",
      "callback_code":"PRODUCT_IS_READY",
      "type":"CALLBACK",
      "code":"PRODUCT_IS_READY",
      "callbackURL":"https://16764cf0511d.ngrok.io/v1/callback",
      "env":"production",
      "status":"is_success",
      "started_at":"2021-10-14T00:33:13.068Z",
      "ended_at":"2021-10-14T00:36:44.195Z",
      "message":"Record callback started!",
      "accountId":"xxxxxxxxxxxxxxxxxxxxx",
      "options":{},
      "meta":{},
}

Explanation

param

Description

confidence

A confidence score measures the overall accuracy of the income stream predictions and projected sum estimates.

projected_yearly_income

Projected yearly income is the total income sum estimated to be made by the user by the end of the year. It uses the monthly_income, number_of_months, and projected_months of each income stream to calculate this figure.

last_two_years_income

This is the total income sum from two years ago. If we are in 2022, this figure is the total income sum from the year 2020.

last_year_income

Last year's income is the income sum from the previous year. If the current year is 2022, last_year_income is income from the year 2021.

last_two_years_to_this_year_projected_income

This is a projected income sum using income figures from the last two years, the last year, and the current year. This is to give a more realistic projected income sum, adjusting for years with either a too high or a too low-income sum.

last_year_to_this_year_projected_income

The *last year to this year's projected income*** uses income figures from the previous year and the current year to estimate the projected sum. It gives a better estimate of the projected sum adjusting for a really high or really low-income figure from the previous year.

number_of_income_streams

This is the number of identified income streams. Each stream has the following:

days

Number of working days during which the income stream was made

income_start_date

The first date the income stream was detected

income_last_date

The date (from the available transactions) the income stream was last identified

avg_monthly_income

The income amount/figure

number_of_months

The total number of months in the year that the income stream was detected

projected_months

This is the estimated number of months in a year for which the income stream would repeat. For instance, if we are in September 2021, and the stream of income has already appeared in every month of the year up until then, it is safe to assume that if all things are equal the stream would continue for the rest of the year, the projected months becomes 12.

employer / source

This is the source of the income stream as identified by the Named Entity Recognition system (NER) which is part of the Okra NLU system.

type

The type of income which is usually one of salary, recurring credit, unstructured.

🚀Now that you understand what Income is, check out API Reference to test the Income API in real-time.


Did this page help you?