API Reference

The NeoScore scoring engine is accessible as a local REST API at http://localhost:5000. No API key required for public endpoints.

No auth for /api/* routes

Session auth for /score/* routes

SHAP explanations included

Scoring

POST/api/score

Pass any subset of the 30 student features. Missing fields are filled with population-median defaults. Returns a score (300–900), risk tier, default probability, percentile rank, SHAP-based top drivers, and a plain-English coaching message.

Shortcut: pass { "persona": "ravi" } to use a built-in demo profile (ravi · priya · deepa).

Request

json

{
  "features": {
    "AMT_INCOME_TOTAL": 300000,
    "AMT_CREDIT": 500000,
    "AMT_ANNUITY": 25000,
    "AGE_YEARS": 32,
    "EMPLOYED_YEARS": 5,
    "FLAG_OWN_REALTY": 1,
    "FLAG_OWN_CAR": 0,
    "CNT_FAM_MEMBERS": 2,
    "CNT_CHILDREN": 0,
    "NAME_EDUCATION_TYPE": "Higher education",
    "NAME_INCOME_TYPE": "Working",
    "NAME_HOUSING_TYPE": "House / apartment",
    "NAME_FAMILY_STATUS": "Married"
  }
}

Response

json

{
  "score": 724,
  "risk_tier": "Good",
  "default_probability": 0.1037,
  "approval_probability": 0.8963,
  "percentile": 71.4,
  "reasoning": "Your employment stability is working in your favour, but your loan-to-income ratio is the biggest drag on your score.",
  "top_features": [
    {
      "feature": "EMPLOYED_YEARS",
      "impact": -0.042
    },
    {
      "feature": "LOAN_TO_INCOME",
      "impact": 0.031
    },
    {
      "feature": "AMT_INCOME_TOTAL",
      "impact": -0.027
    },
    {
      "feature": "ASSET_SCORE",
      "impact": -0.019
    },
    {
      "feature": "EMI_BURDEN",
      "impact": 0.015
    }
  ]
}

Counterfactual Recommendations

POST/api/counterfactual

Given a feature profile, returns the top actionable steps that would increase the score the most. Immutable features (age, family size, region) are automatically excluded.

Request

json

{
  "features": {
    "AMT_INCOME_TOTAL": 120000,
    "AMT_CREDIT": 100000,
    "EMPLOYED_YEARS": 0.8,
    "AGE_YEARS": 28,
    "FLAG_OWN_REALTY": 0
  },
  "max_steps": 3
}

Response

json

{
  "original_score": 551,
  "original_risk": "Very Poor",
  "original_probability": 0.5817,
  "best_reachable_score": 589,
  "moves": [
    {
      "label": "Job tenure",
      "score_delta": 28,
      "effort": "low",
      "timeline_days": 90
    },
    {
      "label": "Annual income",
      "score_delta": 11,
      "effort": "medium",
      "timeline_days": 90
    },
    {
      "label": "Loan amount requested",
      "score_delta": 9,
      "effort": "low",
      "timeline_days": 0
    }
  ]
}

What-If Simulation

POST/api/simulate

Provide a base feature set and a changes dict. Returns both the original and new score so you can measure the exact impact of any hypothetical change.

json

{
  "features": {
    "AMT_INCOME_TOTAL": 120000,
    "EMPLOYED_YEARS": 1
  },
  "changes": {
    "EMPLOYED_YEARS": 3,
    "AMT_INCOME_TOTAL": 150000
  }
}

Demo Personas

All three scoring endpoints accept a persona key as a shortcut:

Ravi

Gig worker, thin file, low income

{ "persona": "ravi" }

Priya

Salaried professional, good profile

{ "persona": "priya" }

Deepa

Self-employed, moderate risk

{ "persona": "deepa" }

Code Examples

JavaScript

const response = await fetch('http://localhost:5000/api/score', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    features: {
      AMT_INCOME_TOTAL: 300000,
      EMPLOYED_YEARS: 5,
      NAME_EDUCATION_TYPE: 'Higher education',
      // ... other features (missing ones use smart defaults)
    }
  })
});
const data = await response.json();
console.log(data.score, data.risk_tier);

Python

python

import requests

response = requests.post(
    "http://localhost:5000/api/score",
    json={
        "features": {
            "AMT_INCOME_TOTAL": 300000,
            "EMPLOYED_YEARS": 5,
            "NAME_EDUCATION_TYPE": "Higher education",
            # missing features use smart defaults
        }
    }
)
data = response.json()
print(f"Score: {data['score']} | Tier: {data['risk_tier']}")

Feature Reference

All 30 student features the model accepts. All are optional — missing values are filled with population medians.

CNT_CHILDRENintNumber of children

CNT_FAM_MEMBERSintFamily size

NAME_EDUCATION_TYPEstringEducation level (Home Credit classes)

NAME_FAMILY_STATUSstringMarital status

NAME_INCOME_TYPEstringIncome type

OCCUPATION_TYPEstringOccupation

ORGANIZATION_TYPEstringEmployer type

NAME_HOUSING_TYPEstringHousing situation

FLAG_OWN_CAR0/1Owns a vehicle

FLAG_OWN_REALTY0/1Owns property

AMT_INCOME_TOTALfloatAnnual income (₹)

AMT_CREDITfloatLoan amount requested (₹)

AMT_ANNUITYfloatMonthly EMI (₹)

AMT_GOODS_PRICEfloatGoods price (₹)

REGION_POPULATION_RELATIVEfloatRegion population density

REGION_RATING_CLIENT1-3Region credit rating

AGE_YEARSfloatAge in years

EMPLOYED_YEARSfloatYears at current employer

+ 12 derived ratio features auto-computed from the above (DEBT_TO_INCOME, EMI_BURDEN, etc.)