Income

Verify Employment and Revenue, Demonstrate Validity, and the Ownership of Identity Data.

How Income Works

Okra allows you to retrieve a full income profile for an individual across all banks in Nigeria —complementing your business’s KYC and hiring processes.

Our income model seeks to calculate users’ credit transactions that can be considered as income - considering that some credits don’t necessarily belong to the user (the money paid in might be for someone else), or could be an outlier (very different from what a user normally receives).

We use different parameters to calculate income and they differ for the different kinds of income models we have:

  • Salary: a fixed amount of money clearly paid into your account by a registered Nigerian company.
  • Recurring incomes: This isn't necessarily salaries, it could be monthly passive returns from investments and businesses.
    • Our Income model tracks quarterly, bi-quarterly, and yearly recurrent inflow.
  • Unstructured income: This type is for those who don’t have a fixed amount of recurring inflow. Small business owners such as butchers, cobblers, and market women belong to this category.

🚧

Confidence Score

Our model comes with a confidence score that calculates how much of a person’s monthly inflow is (was) flagged as income.

Note- Combine Guarantors to give you extra security and shared liability before approving a disbursement or service.

Income information can protect banks, digital services, and end-users. Use the Okra Widget to instantly authenticate your customer's account and retrieve a real-time income profile with the following key details.

Establishing Eligibility for Critical Services

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.

🚀Now that you understand what Income is, check out API Reference to see how Income works

Income Model

Field

Description

id
ObjectID

Unique Auth ID (Unique Okra Identifier)

last_year_income
Number

Amount of available funds in the account

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

Income Endpoints

The /products/income endpoint returns the income for each of a record's customers. It can be used for existing Records that were added via any of Okra’s other products.

curl -X POST https://api.okra.ng/v2/products/income/${route}
-H 'Content-Type: application/json' 
-H 'Authorization: Bearer <secretKey>'

Process Income

You can always process Income directly via the API by making the following call

curl -X POST https://api.okra.ng/v2/products/income/process
-H 'Content-Type: application/json' 
-H 'Authorization: Bearer <secretKey>'
-d '{customer_id: xxxxxxxxxxxxx}'
{
                "_id": "5f80d43c74bsfde5854f64dd",
                "customer": {
                    "_id": "5f6f80fbbfd432187edfbc42",
                    "name": "GAVIN BELSON"
                },
                "__v": 0,
                "confidence": "100.0%",
                "created_at": "2020-10-09T21:21:00.702Z",
                "env": "production",
                "last_updated": "2021-01-12T19:18:12.566Z",
                "last_year_income": 551955.55,
                "max_number_of_overlapping_income_streams": 2,
                "number_of_income_streams": 2,
                "projected_yearly_income": 5151447.24,
                "record": [
                    {
                        "_id": "5fd282be7cd29619734e6a71",
                        "billable_products": [
                            "auth",
                            "balance",
                            "identity",
                            "income",
                            "periodic-transactions"
                        ],
                        "bank": {
                            "_id": "5f63f473d550180010a14bf1",
                            "colors": {
                                "accent": "#BAD306",
                                "bg": "",
                                "button": "#3C4548",
                                "primary": "#3C4548"
                            },
                            "name": "Diamond Bank",
                            "v2_icon": ".. svg data ...",
                            "v2_logo": ".. svg data ...",
                            "icon": "https://okra-images.s3.eu-west-3.amazonaws.com/Diamond+Bank+Icon.svg",
                            "logo": "https://okra-images.s3.eu-west-3.amazonaws.com/Diamond+Bank+Logo.svg"
                        },
                        "env": "production"
                    }
                ],
                "streams": [
                    {
                        "_id": "5ffdf5f41s291e67f63cd786",
                        "account": {
                            "_id": "5f7d90cb45de411ec0bb4780",
                            "bank": {
                                "_id": "5f0cf73e8a8bcc18b8156ad7",
                                "colors": {
                                    "primary": "#401a6e",
                                    "bg": "#41276D",
                                    "button": "#41276D",
                                    "accent": "#00D883",
                                    "icon": "#41276D"
                                },
                                "icon": "https://okra-images.s3.eu-west-3.amazonaws.com/Kuda+icon.svg",
                                "logo": "https://okra-images.s3.eu-west-3.amazonaws.com/Kuda+Bank+Logo+(White).svg",
                                "name": "Kuda Bank",
                                "v2_icon": ".. svg data ...",
                                "v2_logo": ".. svg data ..."
                            }
                        },
                        "avg_monthly_income": 409287.27,
                        "days": 254,
                        "monthly_income": 409287.27,
                        "income_type": "unstructured"
                    }
                ],
                "id": "5f80d43c74b8fdeg854f64dd",
                "status": "completed",
                "banks": [
                    {
                        "_id": "5f0cf73e8a8bcc18b8156ad7",
                        "colors": {
                            "primary": "#401a6e",
                            "bg": "#41276D",
                            "button": "#41276D",
                            "accent": "#00D883",
                            "icon": "#41276D"
                        },
                        "icon": "https://okra-images.s3.eu-west-3.amazonaws.com/Kuda+icon.svg",
                        "logo": "https://okra-images.s3.eu-west-3.amazonaws.com/Kuda+Bank+Logo+(White).svg",
                        "name": "Kuda Bank",
                        "v2_icon": ".. svg data ...",
                        "v2_logo": ".. svg data ..."
                    }
                ]
            }

Request Payload

Definition of All Payload Items from the Routes Below.

Key

Description

Default

page
Number

Page of list you would like to fetch

1

limit
Number

Number of records you would like to fetch

20

pdf
Boolean

Send back as PDF

false

to
Date

YYYY-MM-DD

from
Date

YYYY-MM-DD

customer
ObjectId

Customer's Okra Unique ID

id
ObjectId

Unique Okra Identity ID

Retrieve Balance by Value

Use the baseURL https://api.okra.ng/v2/income/ and append it with any of the available routes.

curl -X POST https://api.okra.ng/v2/income/${route}
-H 'Content-Type: application/json' 
-H 'Authorisation: Bearer <secretKey>'

Route

Payload

Node Function

/getById

id - to - from - pdf

getIncomeById

/getByCustomer

customer - to - from - pdf

getIncomeByCustomer

/getByDate

to - from - pdf

getIncomeByDate

/getByCustomerDate

customer - to - from - pdf

getIncomeByCustomerDate

You can also check our API Reference


What's Next
Did this page help you?