Docs

Credit engine/credit-rules-engine

Credit rules engine

Your team's scoring brain — configurable, versioned rules per loan product, with a complete variable catalog.

7 sections

Credit rules engine

The rules engine is where your team defines how a bank statement becomes a score and a decision. It is declarative — no code, no free-text to evaluate — so every rule is a value you can read, toggle and audit. The engine is per team and per loan product, every edit publishes a new immutable version, and the version that scored an analysis is recorded in its decision trace.

Per team, per product

Rules live at the team level. Each team ships on day one with two default products — a Monthly EMI loan and a Daily EDI loan — and can rename, clone (start from a template), add and turn products on or off. A monthly-EMI product carries only EMI + shared parameters; a daily-EDI product only EDI + shared parameters — a product never shows the other loan type's knobs.

Only a team admin can change rules; any member may read them. Because API keys are per user and scoped to that user's org/team, every org configures and runs analyses under its own ruleset automatically — there is no shared global policy.

Two kinds of rule

A ruleset is an ordered list of rules of two kinds.

Parameter rules

A parameter sets a named policy value the decision consumes. Examples:

ParameterWhat it sets
foirFOIR limit — EMIs as a share of income
min_approve / min_conditionalScore floors for approve / conditional approve
max_explained_riseMost the AI may raise the scorecard score
interest_rate, tenure_months, min_loan_amountHow a repayable EMI becomes a loan offer (EMI product)
abb_emi_cover, cash_weight, implied_emi_rateHow affordability and income are computed
bureau_enabled, bureau_required, bureau_weight, bureau_repull_daysCredit-bureau behaviour
edi_daily_share, edi_min_covered_days, edi_tenure_days, edi_rate, …The daily-loan (EDI) collection model
ai_risk_sense_enabledWhether the AI risk-sense second opinion runs

Numeric parameters can be amount-tiered — the value changes with the requested loan amount.

Condition rules

A condition is feature operator value → action, evaluated against the finished analysis through the variable catalog below. For example bureau shows a written-off account → send to manual review, or gambling detected → flag. Operators are a closed set chosen by the feature's data type:

Data typeOperators
number / money / percent / countgt gte lt lte eq ne between
boolis true / is false
enumeq ne in not in

The four actions

A condition can do exactly one of four things — a closed set the engine actually enforces:

ActionIn the UIEffect
knockout_declineDeclineForces the decision to Decline.
knockout_referSend to manual reviewSends the file to a human.
score_deltaAdjust the scoreAdds or removes signed points from the score.
flagFlag it for the officerRaises a note; no change to score or decision.

Mandatory, optional and locked

Every rule carries three platform flags:

  • Mandatory — always enforced, cannot be switched off. The four safety checks — document-tamper, unreconciled rows, name-mismatch and mule pattern — are mandatory in every product.
  • Optional — ships enabled at a sensible default; the admin may toggle it off or re-tune it (for example 90+ DPD → flag, loan stacking ≥ 5 lenders → flag).
  • Value-locked — the on/off toggle works but the value is fixed by the platform.

A Changed badge marks any rule whose value or on/off state differs from its shipped default, so you can see at a glance what your team has tuned.

Configuring rules (admin UI)

In Rules engine (admin only) each product shows its rules grouped into scoring layers. You can:

  • Toggle a rule on or off (mandatory rules stay on).
  • Edit a value — unless it is locked.
  • Amount bands — switch a numeric parameter from a flat value to "by amount" tiers, and back with "use one flat value".
  • Add a rule — pick any variable from the catalog, a comparison and a value, then an action. Choose "Adjust the score" and enter signed points (negative = penalty, positive = bonus). Custom rules you add can be removed; shipped defaults and parameters cannot.
  • Reset — restore the product to its shipped default ruleset, behind a confirm. A reset is itself a new version, so the change stays in the audit trail.

How a rule actually changes the outcome

Configured rules fold into the decision in one coherent pass, so the score, band, FOIR, decision and offer never contradict each other:

  1. The scorecard + AI committee produce a baseline score.
  2. Every enabled "Adjust the score" rule contributes its signed points (score_delta), applied to the final score before the band, decision, FOIR and offer are derived — a deterministic knob, not an AI claim.
  3. Any knockout downgrades the decision stricter-only and zeroes the offer, so a knocked-out file shows no loan.
  4. The fired rules, their reason codes and the net score delta are stored as the decision trace for audit, under the product and ruleset version that ran.

See scoring layers for the full pipeline and reason-code trace.

The variable catalog

Every condition tests a variable from this catalog — the single source of truth the rule builder reads for its feature dropdown, data types and operators. Adding a new variable server-side makes it appear in the UI automatically; nothing here is hand-maintained in two places.

Score & document

VariableMeaningType
Final credit scoreThe committee's final score after policy (300–900)number
Scorecard scoreThe score before the AI and policy adjust itnumber
Document tampering riskWhether the PDF looks edited (High) or genuine (Low)enum
Unreconciled rows (share)Share of transactions that don't add up to the printed running balancepercent

Capacity & affordability

VariableMeaningType
Average monthly incomeAverage monthly inflow used for affordabilitymoney
Existing EMIs / monthMonthly obligations already being paidmoney
FOIR headroom / monthRoom left under the FOIR limit each monthmoney
Average bank balanceABB across the statement periodmoney
Max new EMI / monthLargest new EMI the statement can supportmoney
Minimum end-of-day balanceThe lowest end-of-day balance in the period — liquidity floormoney

Obligations (bureau ⇄ statement merge)

VariableMeaningType
Merged obligations / monthReconciled bureau + statement EMIs that drive FOIRmoney
Hidden loans (not in bureau)Loan EMIs seen in the statement the bureau doesn't reportcount

Risk

VariableMeaningType
Serious warning signsHow many red risk warnings the statement analysis raisedcount
Active lenders (6 months)Lenders being actively repaid in the last 6 months (loan stacking)count
Pass-through (mule) patternMoney from many unrelated people leaving the same daybool
Payment bounces / returnsTotal bounced / returned transactions across the periodcount

Identity

VariableMeaningType
Statement name matches applicantWhether the account holder is the applicantbool
Name match scoreHow closely the names matchpercent

Applicant (derived, not asked on a form)

VariableMeaningType
Employment typeSalaried if a regular salary drives affordability, else self-employedenum
Applicant ageFrom the bureau's date of birth (only when a bureau report was fetched)number
Applicant genderFrom the bureau (only when a bureau report was fetched)enum

Bureau

VariableMeaningType
Bureau scoreThe credit bureau's scorenumber
Bureau active loansOpen loans on the credit reportcount
Bureau monthly EMI totalTotal monthly EMI across bureau loansmoney
Bureau amount overdueAmount currently overdue on the bureaumoney
Bureau written-off accountsLoans never fully repaid (written off)count
Bureau settled accountsLoans closed for less than the full amount owedcount
Bureau suit-filed accountsLoans a lender has taken to court overcount
Bureau worst days-past-dueMost days ever late on a loancount
Bureau enquiries (90 days)Lenders who checked this applicant's credit in 90 dayscount
Bureau enquiries (30 days)Credit enquiries in the last 30 days — short-window credit hungercount
Bureau total accountsAll loan/card accounts, open + closedcount
Bureau total outstandingTotal current balance owed across active accountsmoney
Credit history length (months)Months since the oldest tradeline opened — thin-file / stabilitycount
Accounts ever 90+ DPDBureau accounts ever 90+ days past due — serious delinquencycount
Accounts currently delinquentActive accounts with an overdue amount or live DPDcount
New loans opened (6 months)Accounts opened in the last 6 months — recent leveragecount
Overdue ÷ outstanding (%)Share of the outstanding balance that is overduenumber
Debt-to-income (%)Total bureau outstanding ÷ annual income (from the statement)number

AI review

VariableMeaningType
AI risk-sense concernAn AI reviewer's overall concern (none / low / medium / high)enum
AI risk-sense findingsHow many extra concerns the AI raised beyond the standard checkscount

Application & LTV

Per-loan anchors the officer enters at upload — data a statement can't provide.

VariableMeaningType
Requested loan amountThe amount asked for — drives LTV and amount tiersmoney
Collateral value — gold / propertyMarket value of the pledged assetmoney
Annual GST turnoverBusiness turnover for MSME / working-capital sizingmoney
Down paymentUpfront amount (vehicle / consumer-durable loans)money
Loan-to-value (LTV %)Requested amount ÷ collateral value, as a percentnumber

Scenarios

LoanPilot detects 26 spending scenarios in the statement; each is auto-registered as two catalog variables you can write rules on:

  • … detected — bool, true when the scenario is present.
  • … — share of outflow (%) — number (0–100), its share of total outflow.

Scenarios are grouped by their signal — risk (gambling, crypto, private lending, legal/fines), stress (medical, digital-lending apps, gold loan/pawn), stability (salary, insurance, staff wages, taxes, utilities), and informational (the rest). Adding a scenario server-side auto-registers its variables here, so the rule builder lists them without any further change.