Configuring your oraculi credit risk rules settings

Every loan application on your Lendsqr platform passes through a decision model before it is approved or declined. The decision model is the set of rules and criteria that determine whether a borrower is eligible for a loan and Oraculi is the engine that executes it.

A well-configured decision model means that good borrowers are approved quickly and consistently, risky applications are declined automatically, and your team spends less time on manual reviews. A poorly configured one can decline good borrowers, approve bad ones, or cause system errors that disrupt your entire lending operation.

This guide explains what a decision model is, how to create and configure one on the Lendsqr admin console, what each available module does, how to sequence them correctly, and how they work together in a real loan application scenario.

What is a decision model?

Credit risk rules refer to a set of predefined rules and criteria that Oraculi uses to evaluate a loan application automatically. When a borrower applies for a loan, Oraculi runs their information through the modules you have configured, in the sequence you have defined, and produces a decision: approve, decline, or offer.

Each lender can create multiple decision models with different risk criteria and assign them to different loan products. For example, you might have a stricter model for larger, unsecured loans and a more permissive model for small, short-term products aimed at returning borrowers.

Decision models are configured entirely in JSON. This gives you a high degree of flexibility and precision but also means that mistakes in the configuration can have real consequences such as declining good borrowers, approving bad ones, or causing system errors. Always review your JSON carefully before saving.

Key terms

Module — a single check or assessment within your decision model, such as a credit bureau check or a karma blacklist check.

Sequence — the order in which modules are executed. Lower numbers run first.

Required — when set to true, Oraculi must successfully execute this module to process the loan decision. When set to false, the module is included in the model but is not mandatory for a decision to be reached.

Continue on failure — when set to false, if a borrower fails this module the evaluation stops immediately and the loan is declined. When set to true, the evaluation continues to the next module even if the borrower fails this one.

Offer on success — used in the Whitelist module. When set to true, if the borrower is whitelisted the system immediately presents a loan offer and skips all remaining modules.

Decision settings — the JSON object where you define the rules and sequences for your modules.

Offer settings — the JSON object where you define the minimum and maximum loan amounts to offer a borrower who passes all modules.

Before you start

Roles and permissions Configuring decision models requires a specific permission. Credit risk rules permission is a separate group from the Loan Products permission and must be explicitly granted to a team member before they can create or edit decision models. To review or update permissions, navigate to Settings and select “Roles and Permissions”.

Plan your model before writing JSON Before opening the admin console, decide on the following:

  • Which modules you want to include and in what order
  • Which modules should be required versus optional
  • Whether each module should continue on failure or stop the evaluation
  • The minimum and maximum loan amounts for your offer settings

Having this planned in advance will make the configuration process faster and reduce the risk of errors.

Types of credit risk rules

This section gives you a clear view of the available decision model modules so you can better understand how your lending decisions are currently being handled.

The available decision model settings (aka modules or services) are as follows:

ModuleDescription
KarmaStatus: REQUIRED. Typically and advisably the first module in the sequence. Checks against the Karma engine. If a user is flagged, they are deemed ineligible. Fields that are checked include BVN, email, phone number etc. Configuration: continue_on_failure should be false for this module. Sample JSON Snippet: { “karma”: { “required”: true, “sequence”: 1, “continue_on_failure”: false } } Sample Payload: { “id”: 1, “version_id”: 1, “decision_model_id”: 1, “decision_type”: “karma”, “setting”: { “check_IP”: { “value”: false }, “check_bvn”: { “value”: true } } }
WhitelistStatus: OPTIONAL. This checks if the user has been whitelisted; if so, the whitelist offer is immediately presented and all other checks are bypassed. continue_on_failure is always true as most users will not be whitelisted. Sample JSON Snippet: { “whitelist”: { “required”: true, “sequence”: 2, “offer_on_success”: true, “continue_on_failure”: true } } Sample Payload: { “id”: 2, “version_id”: 0, “decision_model_id”: 1, “decision_type”: “whitelist”, “setting”: {} }
EcosystemStatus: REQUIRED. The ecosystem module is another Lendsqr internal check. It checks a user against various fields from all organisations housed on the Lendsqr ecosystem. Typical fields checked include past-due loans, running loans, delayed payments, age etc. continue_on_failure should be false. Note: user data is not shared across organisations. Sample JSON Snippet: { “ecosystem”: { “required”: true, “sequence”: 3, “continue_on_failure”: false } } Sample Payload: { “id”: 5, “version_id”: 4, “decision_model_id”: 1, “decision_type”: “ecosystem”, “setting”: { “age”: { “type”: “integer”, “description”: “Age of the borrower”, “minimum”: 23, “maximum”: 55 }, “unique_phone_numbers”: { “type”: “integer”, “description”: “Number of unique phones”, “minimum”: 0, “maximum”: 2 }, “lenders”: { “type”: “integer”, “description”: “Lendsqr Apps that user has signed up to”, “minimum”: 0, “maximum”: 5 } } }
MLStatus: OPTIONAL. Our ML model predicts the outcome of a user’s loan using various properties. Accuracy ~80%. Implemented to provide lenders with insights; hence continue_on_failure is typically true. Interpretation: Prediction = 2 → user will repay. Prediction = 5 → user will not repay. Includes a confidence score. Sample JSON Snippet: { “ml”: { “required”: true, “sequence”: 4, “continue_on_failure”: true } } Sample Payload: { “id”: 3, “version_id”: 1, “decision_model_id”: 1, “decision_type”: “ml”, “setting”: { “prediction”: { “type”: “integer”, “maximum”: 2, “minimum”: 2 }, “confidence_score”: { “type”: “integer”, “maximum”: 100, “minimum”: 50 } } }
ScoringStatus: REQUIRED. A subjective service that rates user attributes and collates them into a credit score. Fields rated include age, gender, marital status, employment, location, etc. continue_on_failure is typically false. Sample JSON Snippet: { “scoring”: { “minimum”: 50, “required”: true, “sequence”: 5, “continue_on_failure”: false } } Sample Payload: { “id”: 4, “version_id”: 4, “decision_model_id”: 1, “decision_type”: “scoring”, “setting”: { “gender”: { “type”: “string”, “weight”: “10”, “attributes”: [ { “key”: “female”, “score”: 10 }, { “key”: “male”, “score”: 5 } ], “description”: “Gender”, “maximum_score”: “10” }, “location”: { “type”: “string”, “weight”: “5”, “attributes”: [ { “key”: “Abia”, “score”: 8 }, { “key”: “Adamawa”, “score”: 1 } ] } } }
Credit BureauStatus: OPTIONAL (External Provider). Data is sourced from one of the three Credit Bureaus in Nigeria (CRC, CreditRegistry, First Central). Fields checked: past-due loans, loan history, active loans, etc. Recommended to set continue_on_failure to false. Sample JSON Snippet: { “credit_bureau”: { “provider”: “CRC”, “required”: false, “sequence”: 6, “continue_on_failure”: false } } Sample Payload: { “id”: 169, “version_id”: 0, “decision_model_id”: 1, “decision_type”: “credit_bureau”, “setting”: { “loan_history”: { “type”: “integer”, “description”: “Number of loans ever gotten”, “minimum”: 0, “maximum”: 100 }, “past_due_loans”: { “type”: “integer”, “description”: “Number of loans past due”, “minimum”: 0, “maximum”: 0 }, “active_loans”: { “type”: “integer”, “description”: “Number of loans active and performing”, “minimum”: 0, “maximum”: 1 }, “last_reported_days”: { “type”: “integer”, “description”: “Days since latest report”, “minimum”: 0, “maximum”: 9999 } } }
BalanceStatus: OPTIONAL (External Provider). Data sourced from external providers delivering customer financial data. Useful for validating account liquidity. continue_on_failure can be true. Sample JSON Snippet: { “balance”: { “provider”: “mono”, “required”: true, “sequence”: 6, “continue_on_failure”: false } } Sample Payload: { “id”: 80, “version_id”: 0, “decision_model_id”: 15, “decision_type”: “balance”, “setting”: { “balance”: { “type”: “float”, “maximum”: 99999999, “minimum”: 1000, “description”: “Balance on the borrower’s account” } } }
StatementStatus: OPTIONAL (External Provider). Data sourced from external providers delivering customer financial statements. Allows checks such as days in debit. continue_on_failure can be true. Sample JSON Snippet: { “statement”: { “provider”: “mono”, “required”: true, “sequence”: 7, “duration”: 180, “continue_on_failure”: true } } Sample Payload: { “id”: 82, “version_id”: 3, “decision_model_id”: 15, “decision_type”: “statement”, “setting”: { “days_in_debit”: { “type”: “integer”, “maximum”: 2, “minimum”: 0, “description”: “Number of days account has been in debit” } } }
IncomeStatus: OPTIONAL (External Provider). Data sourced from providers to estimate borrower’s income. Useful for affordability checks. continue_on_failure can be true. 
Sample JSON Snippet: { “income”: { “provider”: “mono”, “required”: true, “sequence”: 8, “continue_on_failure”: true } } 
Sample Payload: { “id”: 81, “version_id”: 3, “decision_model_id”: 15, “decision_type”: “income”, “setting”: { “income”: { “type”: “float”, “maximum”: 100000000, “minimum”: 50000, “description”: “Estimated borrower income over a stated period” } } }
LociStatus: OPTIONAL. Regulates the number of loans on individual lenders’ platforms by tracking total loan requests. Contact support for more info. 
Sample Payload: { “id”: 260, “version_id”: 7, “decision_model_id”: 1, “decision_type”: “loci”, “setting”: { “loan_requests”: { “type”: “integer”, “description”: “Total number of loan requests made”, “minimum”: 0, “maximum”: 150 } } }

For fields such as id, version_id, decision_model_id, decision_type and setting please note that these are auto-generated and do not require modification. You can only tweak the values of the different variables checked within the settings.

Configuring your oraculi decision model settings

Step-by-step: how to create a credit risk rule

Step 1 — Navigate to credit risk rules

Log in to your Lendsqr admin console. On the left navigation pane, scroll down to Back Office, click on “Product Management”, and select “credit risk rules”. This will open the Decision Models page where all your existing models are listed.

Step 2 — Create a new credit risk rules

Click the “Create” button to start a new decision model. A configuration interface will appear where you can enter your decision settings and offer settings as JSON objects.

Step 3 — Enter your credit risk rules JSON

In the decision settings field, enter the JSON object that defines your modules, their sequence, and their configuration. See the full module reference below for the correct JSON structure for each module.

Step 4 — Enter your offer settings JSON

In the offer settings field, enter the JSON object that defines the loan amount parameters to offer borrowers who pass all your configured modules. For example:

json

{
  "amount": {
    "min": 5000,
    "max": 100000
  }
}

Step 5 — Save the credit risk rules

Once you have reviewed your JSON carefully and confirmed it is correct, click “Save”. The credit risk rules will now appear on the credit risk rules page and can be assigned to a loan product.

Step 6 — Link the credit risk rules to a loan product

Navigate to Back Office, expand “Product Management”, and select “Loan Products”. Open the loan product you want to link the model to, scroll down to the “Decision Models” section, and select the decision model you just created. Save the product.

Real-world example: how modules work together in a loan application

A borrower applies for a ₦50,000 personal loan on a product configured with the following decision model sequence: Karma (sequence 1), Whitelist (sequence 2), Ecosystem (sequence 3), Scoring (sequence 4), Credit Bureau (sequence 5).

Here is how Oraculi processes the application:

  1. Karma check (sequence 1) — Oraculi checks the borrower’s BVN, email, and phone number against the Karma blacklist. The borrower is not flagged. Continue on failure is false, so if they had been flagged, the evaluation would have stopped here and the loan would have been declined. They pass and the evaluation moves to sequence 2.
  2. Whitelist check (sequence 2) — Oraculi checks whether the borrower has been manually prequalified by the lender. They have not been whitelisted. Continue on failure is true, so the evaluation continues to sequence 3.
  3. Ecosystem check (sequence 3) — Oraculi checks the borrower against the Lendsqr ecosystem data, including past due loans, running loans, and delayed payments from across all lenders on the platform. The borrower has no past due loans and only one running loan within the acceptable maximum. They pass and the evaluation continues to sequence 4.
  4. Scoring check (sequence 4) — Oraculi calculates a credit score based on the borrower’s age, gender, employment status, location, and other configured attributes. The borrower scores 68 out of 100, which exceeds the configured minimum of 50. They pass and the evaluation continues to sequence 5.
  5. Credit bureau check (sequence 5) — Oraculi queries the CRC Credit Bureau and retrieves the borrower’s loan history, active loans, and past due records. The borrower has two previous loans with no defaults and zero past due loans, which is within the configured acceptable range. They pass all checks.

Outcome: The borrower has passed all required modules. Oraculi presents a loan offer for ₦50,000 based on the offer settings configured in the model.

Important notes on JSON configuration

  • The fields id, version_id, decision_model_id, and decision_type in the sample payloads are auto-generated by the system. You do not need to enter these manually — only the values within the setting object need to be configured by you.
  • Mistakes in your JSON — such as missing brackets, incorrect field names, or invalid values can cause the decision model to fail silently, decline good borrowers, or approve bad ones. Always validate your JSON before saving.
  • None of the modules are compulsory as a platform rule. You decide which modules to mark as required within your own configuration based on your risk appetite.

For more on how Oraculi was built and the thinking behind it, read how we built Oraculi to help lenders make informed decisions.

Troubleshooting

The credit risk rules option is not visible in the navigation Confirm that your role includes the credit risk rules permission. This is a separate permission from Loan Products and must be explicitly granted. Navigate to Settings and select “Roles and Permissions” to check.

The credit risk rules is declining all borrowers Review your JSON configuration carefully. Common causes include a minimum score set too high in the Scoring module, a maximum of zero set in the past due loans field of the Credit Bureau module when most borrowers have at least one historical entry, or a continue on failure set to false on a module that frequently returns no data.

The credit risk rules is not appearing in the loan product dropdown Confirm that the decision model was saved successfully on the Decision Models page. If it appears there but not in the loan product dropdown, try refreshing the page.

A borrower passed all checks but did not receive an offer Check your offer settings JSON to confirm the minimum and maximum loan amounts are correctly configured. If the offer settings are missing or contain an error, Oraculi may complete the decision without generating an offer.

Frequently asked questions

What is Oraculi? Oraculi is Lendsqr’s automated credit scoring and decision engine. It executes the rules and criteria defined in your decision model to evaluate loan applications automatically.

Can I create more than one credit risk rules? Yes. You can create multiple credit risk rules with different risk criteria and assign them to different loan products. This allows you to apply stricter rules to higher-risk products and more permissive rules to lower-risk ones.

Are any modules compulsory? No. None of the Oraculi modules are compulsory as a platform rule. You configure which modules to include and whether each one is required within your own model.

What does continue on failure mean? When continue on failure is set to false, a borrower who fails that module is immediately declined and no further checks are run. When set to true, the evaluation continues to the next module even if the borrower fails.

Who can configure credit risk rules? Only team members with the credit risk rules permission can create or edit decision models. This is separate from the Loan Products permission and must be explicitly granted by a system administrator.

How do I link a credit risk rules to a loan product? Navigate to the loan product on the admin console, scroll down to the credit risk rules section, and select the decision model you want to link. Save the product to apply the change.

Want to learn more about how our credit risk rules works? Click here.

See also

Was this page helpful?

On this page