Python Library
- Philip Awopetu
Authorization
Setting up your authorization in the Decide Python Library is simple. Simply configure the INDICINA_CLIENT_ID and INDICINA_CLIENT_SECRET as environment variables.
shPython
export INDICINA_CLIENT_ID=my_id
export INDICINA_CLIENT_SECRET=my_secret
If you do not know your INDICINA_CLIENT_ID and INDICINA_CLIENT_SECRET, refer to API Keys to learn how to get them.
Statement
Every statement analysis in Decide begins with a DecideStatement class.
A DecideStatement is how we represent a statement to be analyzed. It can be represented in three ways:
.pdfviaPDFStatement.csv/.xlsxviaCSVStatementjsonviaJSONStatement
PDFStatement
If you need to analyze a PDF statement, use the PDFStatement class. This can be used to create an instance of a PDF statement for Decide.
Param | Type | Default | Description |
|---|---|---|---|
pdf_path |
|
| The path to the PDF file containing the bank statement |
bank |
|
| The bank for which the statement belongs to. |
customer |
|
| An instance of the customer |
currency |
|
| The currency in which the statement is written. |
password |
|
| If the file requires a password to unlock it, pass the password to this argument. |
Sample code:
pytho
from decide import PDFStatement
...
statement = PDFStatement(customer=customer,
pdf_path="statement.pdf",
bank=Bank.ACCESS,
currency=Currency.NGN)
🚧
The file passed to this class must be a valid
CSVStatement
Statements can also come in CSV/XSLX format, use the CSVStatement class. This can be used to create an instance of a CSV statement for Decide analysis.
Param | Type | Default | Description |
|---|---|---|---|
csv_path |
|
| The path to the CSV/XLSX file containing the bank statement |
customer |
|
| An instance of the customer object. |
Sample code:
Python
from decide import CSVStatement
...
statement = CSVStatement(csv_path="AverageOtherIncome.csv",
customer=customer)
🚧
The file passed to this class must be a valid
.csvor.xlsxfile to avoid errors.
JSONStatement
You may have your statement in JSON or a Python dictionary e.g via Mono
Param | Type | Default | Description |
|---|---|---|---|
statement_format |
|
| The format of the statement - MONO, OKRA, MBS OR Custom |
statement |
|
| The bank statement as a Python dictionary |
customer |
|
| An instance of the customer object. |
Sample code
Python
How to Perform a Decide Analysis
Once you have your DecideStatement, simply call the .analyze() method to perform your Decide bank statement analysis.
Sample code:
Python
This returns an instance of the class Analysis, described in the Analysis section.
Customer
A customer is represented by the Customer class. A customer in this sense is someone whose statement is to be analyzed.
Param | Type | Mandatory | Description |
|---|---|---|---|
customer_id |
| Yes | A unique identification of the entity |
| No | Their email address | |
first_name |
| No | Entity's first name |
last_name |
| No | Entity's last name |
phone |
| No | Entity's phone number |
Sample code:
Python
Analysis
When the Decide API sends a response, the response is represented in the Analysis class.
Anatomy of an Analysis
A Decide Analysis is broken down into five major parts, represented in five instance variables:
Variable | Class |
|---|---|
|
|
|
|
|
|
|
|
|
|
BehaviouralAnalysis
This provides a collection of variables associated with the customer's behaviour, giving meaningful insights into the customer's loan repayment habits, gambling rates, and more. Find more info here.
Class Properties
Variable Name | Type | Description |
|---|---|---|
|
| Indicate, taking into account high incidences of fund re-cycling, if whether the account is a secondary/pass-through account. |
|
| Benchmarking the number of betting transactions against total credit turnover on the account (gambling transactions/total credits). Default: |
|
| The result from the benchmarking of credits on the account against debits. Default: |
|
| Any credit transaction as a result of an approved loan over the statement period. Default: |
|
| Benchmarking any loan credits received against the total credits made to the account over the course of the statement period (loans/total credits). Default: |
|
| Benchmarking any debits made for loan repayments against the total credits made to the account over the course of the statement period (loan repayments/total credits). Default: |
|
| Any debit transaction as a result of a loan repayment/repayments towards a loan over the statement period. Default: |
|
| Indicates the name attached to the top crediting account for bank transfers. |
|
| Indicates the name attached to the top destination account for bank transfers. |
CashFlowAnalysis
This provides a collection of variables associated with the customer's behaviour, giving meaningful insights into the customer's loan repayment habits, gambling rates, and more. Find more info here
Class Properties
Variable Name | Type | Description |
|---|---|---|
|
| The percentage of days in which there are either any credit or debit transactions within the account statement period. Bank or tax charges transactions are excluded. |
|
| The customer's average account balance within the statement period. |
|
| The average amount of all credit transactions within the statement period. |
|
| The average amount of all debit transactions within the statement period. |
|
| The balance at the end of the statement. |
|
| Indicates the first day of the bank statement. |
|
| Indicates the last day of the bank statement. |
|
| The transaction duration indicated using the |
|
| This is the monthly average of the total income left in the account less borrowing (loans), sweeping, bills and utilities, charges, expenses, etc. |
|
| The number of months within the statement. |
|
| The total amount of money received within the duration of the bank statement. |
|
| The total amount of debit transactions within the duration of the bank statement. |
|
| The year of the bank statement. |
IncomeAnalysis
This provides a collection of variables associated with the Customer's income. You are provided with information about the customer's average salary, expected salary day, and more. Find more info here.
Class Properties
Variable Name | Type | Description |
|---|---|---|
averageOtherIncome |
| Monthly average of all non-salary transactions detected over the period of the bank statement. |
averageSalary |
| Average of Total Monthly salary transactions detected |
confidenceIntervalOnSalaryDetection |
| Measures (as a percentage) the stability of the detected salary amounts and frequency of the salary payments within the statement period. |
expectedSalaryDay |
| Predicted date of Salary payments. Default: |
lastSalaryDate |
| Indicates the last date a salary was paid over the course of the statement. Default: |
medianIncome |
| Statistical median value of income transactions detected. |
numberOtherIncomePayments |
| Number of Non-Salary income transactions that were detected. |
numberOfSalaryPayments |
| The total number of all Salary transactions detected over the course of the statement. |
salaryEarner |
| Indicate if a consistent, recurring salary was detected over the period of the bank statement. |
salaryFrequency |
| The average number of times a salary is paid monthly. Default: |
gigWorker |
| Indicates if an income is detected from gigs e.g Instagram vendors |
SpendAnalysis
This provides a collection of variables associated with the customer's spending habits. You are given detailed information about the 'how' and 'what' the customer spends on. This includes airtime purchase, entertainment expenses, mobile expenses, bank charges, and more. Find more info here.
Class Properties
Variable Name | Parent | Type | Description |
|---|---|---|---|
atmSpend | expenseChannels |
| Total monthly value of debit transactions incurred through withdrawal at the ATM. |
webSpend | expenseChannels |
| Total monthly value of debit transactions done via online payment. |
posSpend | expenseChannels |
| Total monthly value of debit transactions done via POS payment. |
ussdTransactions | expenseChannels |
| Total monthly value of debit transactions executed via a USSD channel. |
mobileSpend | expenseChannels |
| Total monthly value of expenses paid for mobile related purposes. |
spendOnTransfers | expenseChannels |
| Average monthly value of outbound transfers. |
internationalTransactionsSpend | expenseChannels |
| Total monthly value of all money spent on international transactions (foreign and cross-border). |
|
|
|
|
bills | expenseCategories |
| Total monthly value of debit transactions made for the payment of bills. |
entertainment | expenseCategories |
| Total monthly value of debit transactions incurred by payment at clubs, bars and other entertainment source. |
savingsAndInvestments | expenseCategories |
| Total monthly value of savings and investment done. |
gambling | expenseCategories |
| Total monthly value of debit transactions incurred through spending on gambling during the statement period. |
airtime | expenseCategories |
| Total monthly value of money spent on airtime purchases. |
bankCharges | expenseCategories |
| Total monthly value of debit transactions incurred through bank charges. |
|
|
|
|
averageRecurringExpense |
|
| Total monthly value of any recurring expense detected. |
hasRecurringExpense |
|
| Indicates if a monthly recurring expense was detected. |
totalExpenses |
|
| The total sum of all expenses within the bank statement. |
TransactionPatternAnalysis
This provides a collection of variables associated with the customer's transactions. You are provided with information that will help you understand transaction patterns such as recurring expenses, most frequent transaction range, transactions between range, and more. Find more info here.
Analysis Status
Some bank statement analyses (e.g. PDF) are asynchronous. You may not get the results of the analysis immediately.
You may need to get the status of an analysis. To study how analysis for PDF statement work, study this documentation.
PDFStatus could take one of the following values.
Status | Value | Description |
|---|---|---|
DONE | DONE | The analysis is done |
FAILED | FAILED | The analysis failed |
IN_PROGRESS | IN_PROGRESS | The analysis is still in progress |
📘
Once the analysis status becomes DONE, you will be able to access the Decide variables in the
Analysisobject.
Transaction Tags
The tagging on statements gives insight on each transaction (row level) in the statement processed. Each tagged transaction shows the contribution of that transaction to a corresponding analysis already done or other specific info about the transaction. The output for this is an array of objects in which each object is a row of transaction. For example:
json
To get the tags for a particular row ( or say transaction):
python
Anatomy of Transaction Tags
AccountDetails
Rules Engine Documentation
The Rules Engine enables merchants to set up an automated decisioning process for lending, based on pre-determined conditions tailored to their unique use case. It allows users to:
Develop multiple rule-based conditions
Analyze statements with pre-determined conditions and rules that automate the decision-making process
Automatically filter qualifying applications based on the set rules
Set up an affordability logic to reveal what applicants can pay back
Import Required Libraries
Python
Set Environment Variables
Python
Initialize ScorecardAPI
Python
Create Scorecard
Define Rules
A Rule is defined as a condition to be evaluated on a certain value. You can have as many rules as you need. A Rule consists of several properties, including:
order: an integer representing the order in which the rule is evaluated
rule_type: an Enum representing the type of rule (e.g., average balance, loan amount, etc.)
value: a string representing the value of the rule (e.g., "10000" for an average balance of 10,000)
condition: an ENUM representing the condition to be evaluated (e.g., "is equal to", "less than or equal to", etc.)
operator: an ENUM representing the logical operator to be used when evaluating the rule (e.g., "and", "or", etc.)
For example, the first rule defined in the code states that the average balance of an account must be exactly 10,000.
Python
Create a Block
A Block is a collection of Rule objects that are evaluated together using a logical operator (e.g., "and", "or", etc.). A Block consists of several properties, including:
rules: a list of Rule objects
order: an integer representing the order in which the block is evaluated
operator: an ENUM representing the logical operator to be used when evaluating the block (e.g., "and", "or", etc.)
negative_outcome: an Enum representing the outcome of the block if the evaluation is false
Python
Create a Boolean Rule Set
A BooleanRuleSet is a collection of Block objects that are evaluated together using a logical operator (e.g., "and", "or", etc.). A BooleanRuleSet consists of several properties, including:
name: a string representing the name of the rule set
positive_outcome: an ENUM representing the outcome of the rule set if the evaluation is true
negative_outcome: an ENUM representing the outcome of the rule set if the evaluation is false
owner: a string representing the owner of the rule set
blocks: a list of Block objects
Python
Define Affordability Logic
Affordability logic defines the logic to determine what the applicant can pay back. It is made up of two properties:
monthly_interest_rate: interest rate per month
monthly_durations: a list of Duration objects representing the tenures they wish to provide their service for
Python
Create a Scorecard Request
The ScorecardRequest object is the final object that is created and is used to make requests to the ScorecardAPI. It contains the name of the scorecard, the boolean rule set, the affordability logic, and the status of the scorecard (whether it is enabled or disabled).
Python
Read Scorecard
To retrieve an existing scorecard, we can use the get_scorecard method. The method takes the ID of the scorecard as input and returns a Scorecard object.
Python
Update Scorecard
We can create a new ScorecardRequest object with the updated information and use the update_scorecard method. The method takes the ID of the scorecard and the new ScorecardRequest object as input and updates the scorecard with the new information.
Python
Delete Scorecard
To delete an existing scorecard, we can use the delete_scorecard method. The method takes the ID of the scorecard as input and deletes the scorecard.
Python
Execute Scorecard on Analysis
To execute a scorecard on an existing Analysis, we can use the execute_scorecard method. The method takes the ID of the existing analysis as input and a list of scorecard IDs to run on the analysis.
Python
Analyse statement with Scorecard
To analyse a statement with some already created scorecards/rules, pass in the ids of the scorecards as below:
Python
This concludes the documentation for using the Rules Engine, which covers creating, updating, deleting, and executing scorecards on existing analyses. Use this guide as a reference for implementing the automated decision-making process tailored to your specific lending use case.
Add-Ons
Read this documentation to understand Decide Add-Ons
📘
Support for add-ons will be available in a later version
Enums
Bank
For some statements, you may need to pass the bank name. Supported banks are listed below:
Sample code:
Python
Currency
This is a representation of a currency in the bank statement. You may require it for some types of bank statements.
Supported currencies include
Text
Sample code:
Python
StatementFormat
This is a representation of the type of a bank statement. You may require it for some types of bank statements.
Supported statement formats include:
Sample code:
Python