Risk Scoring

Steward assigns every application a risk score and a per-factor breakdown. This guide explains where risk data appears in the API, how to read the overall score and its band, and how the two scoring strategies differ.

Where risk appears

Surface	How to access it
Application list	GET /api/v1/applications — each item includes a risk object
Application detail	GET /api/v1/applications/{id} — risk on the populated businessApplication or individualApplication
Account configuration	GET /api/v1/account — riskScoreStrategy; GET/PATCH /api/v1/account/{accountId}/risk-settings — the configured factors
Webhooks	risk_score.created when a score is first calculated, risk_score.updated when it is recalculated (see the Webhooks guide)

The risk object is the RiskData schema: an overall score plus a data[] array of per-factor RiskCategory entries.

{
  "risk": {
    "score": 45,
    "data": [
      { "category": "Jurisdiction", "title": "Jurisdiction Risk", "score": 30, "level": "medium" },
      { "category": "PEP", "title": "PEP Risk", "score": 15, "level": "high" }
    ]
  }
}

The overall score and its band

risk.score is a number. The qualitative band — LOW, MEDIUM, HIGH, or PROHIBITED — is not stored on the response; it is derived from the number using the account’s scoring strategy (riskScoreStrategy on the account). The band thresholds differ by strategy:

Band	CUMULATIVE (default)	MAXIMUM
LOW	0–24	0–12
MEDIUM	25–59	13–35
HIGH	60–99	36–99
PROHIBITED	≥ 100	≥ 100

To turn a score into a band, take the account’s riskScoreStrategy and find the row whose lower bound the score meets or exceeds. For example, a score of 45 is MEDIUM under CUMULATIVE but HIGH under MAXIMUM — always band a score against the strategy configured for that account, never a fixed table.

Scoring strategies

Each account uses one of two strategies, exposed as riskScoreStrategy (CUMULATIVE or MAXIMUM, defaulting to CUMULATIVE).

• CUMULATIVE — the overall score is the weighted sum of every factor’s contribution. More risk factors push the score up additively, so the score reflects the accumulation of risk across the profile.
• MAXIMUM — each factor category is scored by its worst-case contributor (e.g. the highest-risk jurisdiction across all owners), and those category scores are summed for the overall.

Under either strategy, a single factor that is itself prohibited pushes the application into the PROHIBITED band.

Reading the per-factor breakdown

Each entry in data[] is one risk factor:

Field	Meaning
category	Identifier for the factor (e.g. Jurisdiction, Country Risk, PEP). The set of factors depends on the strategy, so treat this as an open string, not a fixed enum.
title	Human-readable title for the factor.
score	This factor’s contribution to the overall risk.score.
level	Qualitative level for the factor.

Factor level vs. overall band — two different vocabularies

These are easy to conflate, so read carefully:

• The overall band (derived from risk.score) is uppercase and has four values: LOW, MEDIUM, HIGH, PROHIBITED.
• A factor’s level (data[].level) is lowercase and has five values: low, medium, high, prohibited, and bonus.

Note: bonus is a risk-reducing factor (for example, a regulated entity) that lowers the overall score. It only ever appears on a factor’s level, never as an overall band.

Configuring risk

The factors and their weightings are configured per account and returned by GET /api/v1/account/{accountId}/risk-settings. Update them with PATCH to the same endpoint. Changing risk settings or the underlying application data triggers a recalculation, delivered as a risk_score.updated webhook.