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, its authoritative band, and a data[] array of per-factor RiskCategory entries.

{
  "risk": {
    "score": 45,
    "band": "MEDIUM",
    "data": [
      { "category": "Jurisdiction", "title": "Incorporated in Brazil", "score": 25, "level": "medium" },
      { "category": "PEP", "title": "Politically exposed person found in the company structure", "score": 20, "level": "high" }
    ]
  }
}

The band above is MEDIUM because this account uses the default CUMULATIVE strategy. The same score of 45 would band as HIGH on a MAXIMUM account, which is exactly why you should read band rather than deriving it yourself.

The overall score and its band

risk.score is a number. risk.band is the authoritative qualitative band (LOW, MEDIUM, HIGH, or PROHIBITED) derived by Steward from that number using the account’s scoring strategy (riskScoreStrategy on the account). Render risk.band when it is present rather than applying fixed client-side thresholds. The band is derived at response time and is not stored separately on the application.

The 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

When calculating outside an application response, 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.

What goes into a score

Scoring is factor-based. Each factor is scored independently, multiplied by its configured weight, and combined according to the account’s strategy. The configurable factors are a fixed set of eleven, returned by GET /api/v1/account/{accountId}/risk-settings as RiskFactorName values:

Factor	What it measures	Default weight
JURISDICTION	Country risk across the entity and its owners	1.0
REGULATED	Whether the entity is regulated (the one risk-reducing factor)	1.0
SOURCE_OF_WEALTH	Origin of the funds or wealth behind the entity	0.8
PEP	Politically exposed persons in the structure	0.75
SANCTIONS	Sanctions exposure	0.75
WATCHLIST	Watchlist and other warning listings	0.75
ADVERSE_MEDIA	Negative news coverage	0.6
OWNERSHIP	Ownership complexity: simple, layered, or complex	0.3
INDUSTRY	Sector risk, including prohibited sectors	0.2
LEGAL_ENTITY_TYPE	The entity’s legal form	0.2
ENTITY_AGE	Time since incorporation	0.1

Weights and per-option scores are account configuration, not platform constants. The values above are the defaults a new account starts from. Read the account’s own risk settings rather than assuming them, and expect them to differ between your accounts.

How screening feeds risk

PEP, SANCTIONS, WATCHLIST, and ADVERSE_MEDIA are driven by screening results rather than by data you submit. Confirming or dismissing a hit therefore changes the score: recording a review decision on a hit re-triggers risk calculation, and the recalculated score arrives as a risk_score.updated webhook. A dismissed false positive stops contributing; a confirmed match starts.

Risk-reducing factors

REGULATED is the one factor that can lower a score, because a regulated entity carries a negative contribution, and its data[] entry has level: "bonus" rather than a risk level. That is why a factor’s contribution can be negative and why summing only the positive entries will not reproduce risk.score.

Breakdown categories by strategy

The category values you see in data[] are display labels, and the two strategies genuinely produce different sets. This is why category is an open string rather than an enum. Neither list is a stable contract; match defensively and fall back to rendering title.

Under CUMULATIVE:

Jurisdiction · Legal Entity · Ownership · Industry · Entity Age · PEP · Sanctions · Watchlist · Adverse Media · Source of Wealth · Regulated

Under MAXIMUM:

Country Risk · Legal Structure · Entity Age · PEP · Sanctions · Adverse Media · Adverse Media (UBO) · Payment Activity · Transaction Volume · Regulated Entity

Note that the same underlying concept is labelled differently between the two: jurisdiction risk is Jurisdiction under CUMULATIVE and Country Risk under MAXIMUM. A factor also only appears when it applies: an application with no incorporation date produces no Entity Age entry at all, so treat every category as optional.

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. Each field you send replaces the stored value as a whole: factors is the complete factor list, so a factor you leave out reverts to its default, and screeningTaxonomy is the complete taxonomy. Send only the fields you mean to replace, and read the current settings first. Changing risk settings or the underlying application data triggers a recalculation, delivered as a risk_score.updated webhook.