Behavioural Analysis

The Behavioural Analysis API provides an in-depth financial and behavioral assessment based on the account statement of a user. By analyzing the transaction history, spending patterns, income, and other financial activities, the API helps in understanding the user’s financial behavior, risk profile, and overall financial health. This can be particularly useful for financial institutions, credit scoring, risk assessment, and customer segmentation.

Generate Account ID

Request

[POST]

{{baseUrl}}/api/v1/financial/transactions/pdf

Header

Header	Type	Description
AppId	string	Create an app to get your app ID on dashboard here
Authorization	string	Private/secret key. Use <key> not Bearer <key>

Body parameter

Parameter	Type	Description	Required
bank_code	string	Bank code of Customer	required
statement	file	PDF document of Customer’s statement of account	required

Sample response

Response

{
    "entity": {
        "acct_id": "1234a5b6-20bb-4e16-b711-56c5bd7a3c90"
    }
}

Response Fields

Field	Type	Description
entity	object	Contains the account generation response data
entity.acct_id	string	Unique account identifier used for subsequent financial analysis requests

Financial Analysis

Request

[GET]

{{baseUrl}}/api/v1/financial/analysis

Header

Header	Type	Description
AppId	string	Create an app to get your app ID on dashboard here
Authorization	string	Private/secret key. Use <key> not Bearer <key>

Query parameter

Parameter	Type	Description	Required
account_id	string	Account ID generated from the API here	required

Sample response

Response

{
    "entity": {
        "accountBreakdown": {
            "TotalCreditEntry": 306935.75,
            "TotalDebitMade": 321986.57,
            "averageMonthlyBalance": 0,
            "averageMonthlyCredits": 25577.98,
            "averageMonthlyDebits": 20124.16,
            "averageWeeklyBalance": 0,
            "averageWeeklyCredits": 6530.55,
            "averageWeeklyDebits": 5031.04,
            "closingBalance": 0,
            "firstDateInStatement": "2021-04-12",
            "lastDateInStatement": "2022-07-03",
            "numberOfTransactingMonths": 6,
            "periodInStatement": "April - July",
            "yearInStatement": "2021, 2022"
        },
        "expenseBreakdown": {
            "MaximumExpense": "pos web pmt John Doe b aso l00ng",
            "atmLocations": [
                "lagos",
                "yabatech",
                "yaba"
            ],
            "averageMonthlyExpenseOnAirtimeandData": 2200,
            "averageMonthlyExpenseOnAtmAndPOS": 39663.05,
            "averageMonthlyExpenseOnChargesAndStampDuty": 108.88,
            "averageMonthlyExpenseOnEntertainment": 168.46,
            "averageMonthlyExpenseOnGambling": 0,
            "averageMonthlyExpenseOnHealth": 91.67,
            "averageMonthlyExpenseOnHospitalityandFood": 0,
            "averageMonthlyExpenseOnInsurance": 0,
            "averageMonthlyExpenseOnInternationalTransactions": 0,
            "averageMonthlyExpenseOnOnlineandWeb": 24955.55,
            "averageMonthlyExpenseOnRent": 0,
            "averageMonthlyExpenseOnSavingsAndInvestments": 0,
            "averageMonthlyExpenseOnTransfer": 11692.5,
            "averageMonthlyExpenseOnTransportation": 0,
            "averageMonthlyExpenseOnUSSD": 333.33,
            "averageMonthlyExpenseOnUtilities": 0,
            "averageMonthlyExpenseonTravel": 0,
            "averageMonthlyRecurringExpenses": 0,
            "averageMonthlyTotalExpenses": 53555.55,
            "minimumSalary": 653.25,
            "monthWithmaximumExpense": "2/2022",
            "mostFrequentExpense": "atm_and_pos_transactions",
            "mostFrequentExpenseCategory": "atm_and_pos_transactions",
            "totalExpenseOnAirtimeAndData": 13200,
            "totalExpenseOnInternationalTransactions": 0,
            "totalExpenseOnSavingsAndInvestments": 0,
            "totalExpenseOnTransfer": 70155.02,
            "totalExpenseOnTransportation": 0,
            "totalExpenseOnTravel": 0,
            "totalExpenseOnUSSD": 2000,
            "totalExpenseOnUtilities": 0,
            "totalExpenseonChargesAndStampDuty": 237978.3,
            "totalExpenseonEntertainment": 1010.75,
            "totalExpenseonGambling": 0,
            "totalExpenseonHealth": 550,
            "totalExpenseonHospitalityandFood": 0,
            "totalExpenseonInsurance": 0,
            "totalExpenseonOnlineandWeb": 149733.3,
            "totalMonthlyExpenses": 321333.32,
            "totalRecurringExpenses": 0
        },
        "fundsManagement": {
            "accountActivity": 0.1,
            "accountSweep": "No",
            "averageMonthlyLoanAmount": 0,
            "averageMonthlyLoanRepaymentAmount": 0,
            "gamblingRate": 0,
            "gamblingStatus": "No Gambling Transactions Found",
            "loanInflowAmount": null,
            "loanRepaymentToInflowAmount": 0,
            "monthToMonthInflowToOutflowAmount": "Positive Cash Flow",
            "numberOfCreditLoanTransactions": null,
            "numberOfDebitRepaymentTransactions": null,
            "overallInflowToOutflowAmount": "Negative Cash Flow",
            "percentOfInflowIrregularity": 0,
            "totalLoanAmount": 0,
            "totalLoanRepaymentAmount": 0
        },
        "inflowBreakdown": {
            "AdditionalIncome": "Yes",
            "RecurringSalaryPayments": null,
            "aSalaryEarner": "No",
            "averageAdditionalIncome": 9166.67,
            "averageGuaranteedSalary": 0,
            "estimatedSalaryPaymentDay": null,
            "lastDateOfSalaryPayment": null,
            "minimumSalary": 0,
            "netAverageMonthlySalary": 0,
            "numberOfAdditionalIncomePayments": 2,
            "totalnumberOfSalaryPayments": 0
        },
        "transactionRoutineBreakdown": {
            "MaximumExpense": 0,
            "lastCreditReceived": "2022-03-04",
            "lastDebitMade": "2022-07-03",
            "mostFrequentBalanceRange": "<10000",
            "mostFrequentTransactionRange": "<10000",
            "numberOfCardRequests": 0,
            "percentNumberOfDaysBalanceWasLessThan10ThousandNaira": 1,
            "percentNumberOfDaysTransactionsWasLessThan10ThousandNaira": 0.96,
            "percentOfBalancesBetween100ThousandTo500ThousandNaira": 0,
            "percentOfBalancesBetween10ThousandTo100ThousandNaira": 0,
            "percentOfBalancesBetween500ThousandToOneMillionNaira": 0,
            "percentOfBalancesGreaterThanOneMillionNaira": 0,
            "percentOfBalancesLessThan10ThousandNaira": 1,
            "percentOfTransactionsBetween100ThousandTo500ThousandNaira": 0,
            "percentOfTransactionsBetween10ThousandTo100ThousandNaira": 0.12,
            "percentOfTransactionsBetween500ThousandToOneMillionNaira": 0,
            "percentOfTransactionsGreaterThanOneMillionNaira": 0,
            "percentOfTransactionsLessThan10ThousandNaira": 0.88,
            "percentofCreditTransactions": 0.19,
            "percentofDebitTransactions": 0.81,
            "totalAmountOfTransactions": 129
        }
    }
}

Response Fields

Field	Type	Description
entity	object	Contains the financial analysis response data
entity.accountBreakdown	object	Summary of account activity and balances over the statement period
entity.accountBreakdown.TotalCreditEntry	number	Total value of all credit (inflow) transactions
entity.accountBreakdown.TotalDebitMade	number	Total value of all debit (outflow) transactions
entity.accountBreakdown.averageMonthlyBalance	number	Average monthly account balance
entity.accountBreakdown.averageMonthlyCredits	number	Average monthly credit (inflow) amount
entity.accountBreakdown.averageMonthlyDebits	number	Average monthly debit (outflow) amount
entity.accountBreakdown.averageWeeklyBalance	number	Average weekly account balance
entity.accountBreakdown.averageWeeklyCredits	number	Average weekly credit (inflow) amount
entity.accountBreakdown.averageWeeklyDebits	number	Average weekly debit (outflow) amount
entity.accountBreakdown.closingBalance	number	Account balance at the end of the statement period
entity.accountBreakdown.firstDateInStatement	string	Start date of the statement period
entity.accountBreakdown.lastDateInStatement	string	End date of the statement period
entity.accountBreakdown.numberOfTransactingMonths	number	Number of months with recorded transactions
entity.accountBreakdown.periodInStatement	string	Human-readable summary of the statement period
entity.accountBreakdown.yearInStatement	string	Year(s) covered by the statement
entity.expenseBreakdown	object	Categorized breakdown of spending patterns
entity.expenseBreakdown.MaximumExpense	string	Description of the single highest expense transaction
entity.expenseBreakdown.atmLocations	array	List of ATM locations where withdrawals were made
entity.expenseBreakdown.averageMonthlyExpenseOnAirtimeandData	number	Average monthly spend on airtime and data
entity.expenseBreakdown.averageMonthlyExpenseOnAtmAndPOS	number	Average monthly spend on ATM withdrawals and POS transactions
entity.expenseBreakdown.averageMonthlyExpenseOnChargesAndStampDuty	number	Average monthly bank charges and stamp duty
entity.expenseBreakdown.averageMonthlyExpenseOnEntertainment	number	Average monthly spend on entertainment
entity.expenseBreakdown.averageMonthlyExpenseOnGambling	number	Average monthly spend on gambling
entity.expenseBreakdown.averageMonthlyExpenseOnHealth	number	Average monthly spend on health-related expenses
entity.expenseBreakdown.averageMonthlyExpenseOnHospitalityandFood	number	Average monthly spend on hospitality and food
entity.expenseBreakdown.averageMonthlyExpenseOnInsurance	number	Average monthly spend on insurance
entity.expenseBreakdown.averageMonthlyExpenseOnInternationalTransactions	number	Average monthly spend on international transactions
entity.expenseBreakdown.averageMonthlyExpenseOnOnlineandWeb	number	Average monthly spend on online and web purchases
entity.expenseBreakdown.averageMonthlyExpenseOnRent	number	Average monthly spend on rent
entity.expenseBreakdown.averageMonthlyExpenseOnSavingsAndInvestments	number	Average monthly amount moved to savings or investments
entity.expenseBreakdown.averageMonthlyExpenseOnTransfer	number	Average monthly spend on bank transfers
entity.expenseBreakdown.averageMonthlyExpenseOnTransportation	number	Average monthly spend on transportation
entity.expenseBreakdown.averageMonthlyExpenseOnUSSD	number	Average monthly spend via USSD transactions
entity.expenseBreakdown.averageMonthlyExpenseOnUtilities	number	Average monthly spend on utilities
entity.expenseBreakdown.averageMonthlyExpenseonTravel	number	Average monthly spend on travel
entity.expenseBreakdown.averageMonthlyRecurringExpenses	number	Average monthly recurring expense amount
entity.expenseBreakdown.averageMonthlyTotalExpenses	number	Average total monthly expenses across all categories
entity.expenseBreakdown.minimumSalary	number	Minimum detected salary payment
entity.expenseBreakdown.monthWithmaximumExpense	string	Month with the highest total expenses
entity.expenseBreakdown.mostFrequentExpense	string	Most frequently occurring expense type
entity.expenseBreakdown.mostFrequentExpenseCategory	string	Category of the most frequent expense
entity.expenseBreakdown.totalExpenseOnAirtimeAndData	number	Total spend on airtime and data
entity.expenseBreakdown.totalExpenseOnInternationalTransactions	number	Total spend on international transactions
entity.expenseBreakdown.totalExpenseOnSavingsAndInvestments	number	Total amount moved to savings or investments
entity.expenseBreakdown.totalExpenseOnTransfer	number	Total spend on bank transfers
entity.expenseBreakdown.totalExpenseOnTransportation	number	Total spend on transportation
entity.expenseBreakdown.totalExpenseOnTravel	number	Total spend on travel
entity.expenseBreakdown.totalExpenseOnUSSD	number	Total spend via USSD transactions
entity.expenseBreakdown.totalExpenseOnUtilities	number	Total spend on utilities
entity.expenseBreakdown.totalExpenseonChargesAndStampDuty	number	Total bank charges and stamp duty
entity.expenseBreakdown.totalExpenseonEntertainment	number	Total spend on entertainment
entity.expenseBreakdown.totalExpenseonGambling	number	Total spend on gambling
entity.expenseBreakdown.totalExpenseonHealth	number	Total spend on health-related expenses
entity.expenseBreakdown.totalExpenseonHospitalityandFood	number	Total spend on hospitality and food
entity.expenseBreakdown.totalExpenseonInsurance	number	Total spend on insurance
entity.expenseBreakdown.totalExpenseonOnlineandWeb	number	Total spend on online and web purchases
entity.expenseBreakdown.totalMonthlyExpenses	number	Total expenses across the statement period
entity.expenseBreakdown.totalRecurringExpenses	number	Total recurring expenses across the statement period
entity.fundsManagement	object	Assessment of the user’s financial management behavior
entity.fundsManagement.accountActivity	number	Account activity ratio (0–1)
entity.fundsManagement.accountSweep	string	Whether account sweep activity was detected (Yes or No)
entity.fundsManagement.averageMonthlyLoanAmount	number	Average monthly loan amount received
entity.fundsManagement.averageMonthlyLoanRepaymentAmount	number	Average monthly loan repayment amount
entity.fundsManagement.gamblingRate	number	Ratio of gambling transactions to total transactions
entity.fundsManagement.gamblingStatus	string	Summary of gambling activity (e.g., No Gambling Transactions Found)
entity.fundsManagement.loanInflowAmount	number|null	Total loan inflow amount
entity.fundsManagement.loanRepaymentToInflowAmount	number	Ratio of loan repayments to total inflows
entity.fundsManagement.monthToMonthInflowToOutflowAmount	string	Monthly cash flow assessment (e.g., Positive Cash Flow)
entity.fundsManagement.numberOfCreditLoanTransactions	number|null	Count of credit/loan inflow transactions
entity.fundsManagement.numberOfDebitRepaymentTransactions	number|null	Count of loan repayment transactions
entity.fundsManagement.overallInflowToOutflowAmount	string	Overall cash flow assessment (e.g., Negative Cash Flow)
entity.fundsManagement.percentOfInflowIrregularity	number	Percentage of irregular inflows (0–1)
entity.fundsManagement.totalLoanAmount	number	Total loan amount received
entity.fundsManagement.totalLoanRepaymentAmount	number	Total loan repayment amount
entity.inflowBreakdown	object	Analysis of income sources and salary patterns
entity.inflowBreakdown.AdditionalIncome	string	Whether additional income sources were detected (Yes or No)
entity.inflowBreakdown.RecurringSalaryPayments	string|null	Details of recurring salary payments
entity.inflowBreakdown.aSalaryEarner	string	Whether the user is identified as a salary earner (Yes or No)
entity.inflowBreakdown.averageAdditionalIncome	number	Average additional (non-salary) income per month
entity.inflowBreakdown.averageGuaranteedSalary	number	Average guaranteed salary amount per month
entity.inflowBreakdown.estimatedSalaryPaymentDay	string|null	Estimated day of the month salary is received
entity.inflowBreakdown.lastDateOfSalaryPayment	string|null	Date of the most recent salary payment
entity.inflowBreakdown.minimumSalary	number	Minimum detected salary payment amount
entity.inflowBreakdown.netAverageMonthlySalary	number	Net average monthly salary
entity.inflowBreakdown.numberOfAdditionalIncomePayments	number	Count of additional income payments detected
entity.inflowBreakdown.totalnumberOfSalaryPayments	number	Total number of salary payments detected
entity.transactionRoutineBreakdown	object	Analysis of transaction patterns and balance distribution
entity.transactionRoutineBreakdown.MaximumExpense	number	Maximum single expense transaction amount
entity.transactionRoutineBreakdown.lastCreditReceived	string	Date of the last credit transaction
entity.transactionRoutineBreakdown.lastDebitMade	string	Date of the last debit transaction
entity.transactionRoutineBreakdown.mostFrequentBalanceRange	string	Most common account balance range
entity.transactionRoutineBreakdown.mostFrequentTransactionRange	string	Most common transaction amount range
entity.transactionRoutineBreakdown.numberOfCardRequests	number	Number of card replacement or issuance requests
entity.transactionRoutineBreakdown.percentNumberOfDaysBalanceWasLessThan10ThousandNaira	number	Proportion of days balance was below ₦10,000 (0–1)
entity.transactionRoutineBreakdown.percentNumberOfDaysTransactionsWasLessThan10ThousandNaira	number	Proportion of days transaction totals were below ₦10,000 (0–1)
entity.transactionRoutineBreakdown.percentOfBalancesBetween100ThousandTo500ThousandNaira	number	Proportion of days balance was ₦100,000–₦500,000 (0–1)
entity.transactionRoutineBreakdown.percentOfBalancesBetween10ThousandTo100ThousandNaira	number	Proportion of days balance was ₦10,000–₦100,000 (0–1)
entity.transactionRoutineBreakdown.percentOfBalancesBetween500ThousandToOneMillionNaira	number	Proportion of days balance was ₦500,000–₦1,000,000 (0–1)
entity.transactionRoutineBreakdown.percentOfBalancesGreaterThanOneMillionNaira	number	Proportion of days balance exceeded ₦1,000,000 (0–1)
entity.transactionRoutineBreakdown.percentOfBalancesLessThan10ThousandNaira	number	Proportion of days balance was below ₦10,000 (0–1)
entity.transactionRoutineBreakdown.percentOfTransactionsBetween100ThousandTo500ThousandNaira	number	Proportion of transactions between ₦100,000–₦500,000 (0–1)
entity.transactionRoutineBreakdown.percentOfTransactionsBetween10ThousandTo100ThousandNaira	number	Proportion of transactions between ₦10,000–₦100,000 (0–1)
entity.transactionRoutineBreakdown.percentOfTransactionsBetween500ThousandToOneMillionNaira	number	Proportion of transactions between ₦500,000–₦1,000,000 (0–1)
entity.transactionRoutineBreakdown.percentOfTransactionsGreaterThanOneMillionNaira	number	Proportion of transactions exceeding ₦1,000,000 (0–1)
entity.transactionRoutineBreakdown.percentOfTransactionsLessThan10ThousandNaira	number	Proportion of transactions below ₦10,000 (0–1)
entity.transactionRoutineBreakdown.percentofCreditTransactions	number	Proportion of transactions that are credits (0–1)
entity.transactionRoutineBreakdown.percentofDebitTransactions	number	Proportion of transactions that are debits (0–1)
entity.transactionRoutineBreakdown.totalAmountOfTransactions	number	Total number of transactions in the statement