{
  "service": "Creditcrest Score",
  "version": "3.0.0",
  "stores": "nothing",
  "says": "Creditcrest Score compares an applicant with the lender’s borrowers who repaid. It is not a credit decision, it declines nobody, and until it is validated on the lender’s own outcomes it is uncalibrated.",
  "scales": {
    "elo": "Against the lender’s model borrower for the loan type: the gap to it, laid on its rating, which started at 800 and moves with the lender’s outcomes. 150 points is ten times the odds; there is no upper or lower limit.",
    "plain": "A plain score from 0 to 1200, each measure read against fixed scales and compared with nobody."
  },
  "riskClasses": {
    "says": "Creditcrest risk classes: the lender’s own, not a credit rating. On the rating, each class is a range of the chance the loan is not repaid in full (pd, a fraction). riskClassNotch is worked out always; show it only when calibrated is true.",
    "elo": [
      {
        "riskClass": "AAA",
        "pd": {
          "from": 0,
          "to": 0.005
        },
        "says": "Fewer than 1 in 200 expected not to be repaid in full."
      },
      {
        "riskClass": "AA",
        "pd": {
          "from": 0.005,
          "to": 0.01
        },
        "says": "1 in 200 to 1 in 100 expected not to be repaid in full."
      },
      {
        "riskClass": "A",
        "pd": {
          "from": 0.01,
          "to": 0.02
        },
        "says": "1 in 100 to 1 in 50 expected not to be repaid in full."
      },
      {
        "riskClass": "BBB",
        "pd": {
          "from": 0.02,
          "to": 0.04
        },
        "says": "1 in 50 to 1 in 25 expected not to be repaid in full."
      },
      {
        "riskClass": "BB",
        "pd": {
          "from": 0.04,
          "to": 0.08
        },
        "says": "1 in 25 to about 1 in 12 expected not to be repaid in full."
      },
      {
        "riskClass": "B",
        "pd": {
          "from": 0.08,
          "to": 0.15
        },
        "says": "About 1 in 12 to about 1 in 7 expected not to be repaid in full."
      },
      {
        "riskClass": "CCC",
        "pd": {
          "from": 0.15,
          "to": 0.3
        },
        "says": "About 1 in 7 to about 3 in 10 expected not to be repaid in full."
      },
      {
        "riskClass": "CC",
        "pd": {
          "from": 0.3,
          "to": 1
        },
        "says": "About 3 in 10 or more expected not to be repaid in full."
      }
    ],
    "plain": {
      "says": "On the plain scale a class is fixed points out of 1200, not a chance of default.",
      "classes": [
        {
          "riskClass": "AAA",
          "points": {
            "from": 1185,
            "to": 1200
          },
          "says": "Full marks, or nearly, on every measure."
        },
        {
          "riskClass": "AA",
          "points": {
            "from": 1160,
            "to": 1184
          },
          "says": "Strong on every measure."
        },
        {
          "riskClass": "A",
          "points": {
            "from": 1130,
            "to": 1159
          },
          "says": "Strong on nearly every measure."
        },
        {
          "riskClass": "BBB",
          "points": {
            "from": 1100,
            "to": 1129
          },
          "says": "Good on nearly every measure."
        },
        {
          "riskClass": "BB",
          "points": {
            "from": 900,
            "to": 1099
          },
          "says": "Good on most measures."
        },
        {
          "riskClass": "B",
          "points": {
            "from": 670,
            "to": 899
          },
          "says": "Adequate, with some measures weak."
        },
        {
          "riskClass": "CCC",
          "points": {
            "from": 410,
            "to": 669
          },
          "says": "Weak on several measures."
        },
        {
          "riskClass": "CC",
          "points": {
            "from": 0,
            "to": 409
          },
          "says": "Weak on most measures."
        }
      ]
    },
    "loans": {
      "riskClass": "D",
      "says": "In default (90 or more days past due) or written off. A loan’s class, never an applicant’s."
    },
    "notches": "Notches (+ and −) are shown once the score is validated on the lender’s own outcomes. Before that they would be false precision."
  },
  "keeps": "Nothing. A lender that keeps its own records sends the model borrower and a loan’s rating history in, and keeps what comes back. A lender hosted on Creditcrest has them kept in its own records: GET /v1/l.",
  "endpoints": {
    "POST /v1/score": {
      "what": "Score an applicant against the lender’s model borrower, or on the plain scale out of 1200, with its risk class (AAA to CC) and, on the rating, the chance it is not repaid in full. The answer carries the first entry of the rating history, to keep.",
      "body": "{ statement (CSV text) | application (reading, assessment, history, answers…), amount, termMonths, frequency, scale: elo | plain, loanType?, model? (the model borrower for the loan type, as /v1/score/model-borrower returned it), lender?, reference? (the application’s), loan? }"
    },
    "POST /v1/score/model-borrower": {
      "what": "Count completed and written-off loans in the lender’s model borrower for one loan type, up to 25 a call: its own rating moves with each by K × (result − expected). Its profile is Creditcrest’s shared one for the type. A write-off with hardship relief is a loss, counted apart. Send it back each time; each loan counts once.",
      "body": "{ model? | lender, loanType?: sacc | macc | personal | secured | car | business, loans: [{ loan, application?, outcome: completed | written off | written off with hardship relief, on, good: repaid and never over 7 days past due, rated: the history’s first entry (scale, rating, measures) }] }"
    },
    "POST /v1/score/history": {
      "what": "Bring a loan’s rating history up to a day from its ledger: every repayment, dishonour, cleared arrears, early payout, completion or write-off (with hardship relief or not) since, each once, with the risk class before and after. Hardship never lowers it.",
      "body": "{ history: [the entries so far, first to last], terms, events (the ledger’s events), through: YYYY-MM-DD, graceDays?, model? }"
    },
    "POST /v1/score/benchmark": {
      "what": "Build a model borrower’s profile from closed loans in one go.",
      "body": "{ loans: [{ measures, outcome: good|bad|neither, closedOn }], from?, to? }"
    },
    "POST /v1/score/validate": {
      "what": "How well the score separates good and bad loans: AUC, Gini, KS and the bad rate in each risk class beside the range it stands for.",
      "body": "{ loans: [{ rating, outcome }] }"
    },
    "POST /v1/score/update": {
      "what": "Move a rating by repayment results: each instalment is a match.",
      "body": "{ rating, results: [{ result: on time|late|missed|plan kept }], baseRate? }"
    }
  }
}