Scoring & decisioning — how a screen becomes a decision

This is the one authoritative page for how PROOViD AML turns a name you submit into a match classification, a 0–100 risk score and band, and a final Pass / Review / Fail decision. Nothing here is a black box: every number and every branch is drawn straight from the scoring engine, and §5 is a worked example you can reproduce yourself with two curl calls. For how the underlying watchlist data is built see How the data is built; for the response shape see API reference. Deeper source-of-truth notes live in the engineering docs docs/decision-criteria.md, docs/decision-matrix.md and docs/decision-priority.md, which this page consolidates.

1 · The pipeline, end to end

Every screen runs the same five ordered stages. Each stage's output is the next stage's input, and the response returns the artefacts of all five.

1. Retrieval. Candidate entities are pulled from the watchlist corpus by a Postgres trigram (pg_trgm) name search, optionally widened by phonetic and nickname expansion. This stage is about recall — cast a wide net; precision is imposed downstream.
2. Classification. Each candidate is judged on the name × date-of-birth axis into TruePositive (full name + exact full-DoB agreement), PotentialMatch (a real hit a human should confirm), or FalsePositive (ruled out — a different person). Only TruePositive and PotentialMatch are real and carry forward.
3. Scoring. The real matches produce a single riskScore (0–100) and a riskBand (Minimal / Low / Medium / High) — §2.
4. Decision. Each real match is resolved through the tenant's decision matrix to a base Pass / Review / Fail, then aggregated (worst wins) and adjusted by the band policy and floors — §4.
5. Return. The response carries isMatch, score, classification, riskScore, riskBand, decision, the reasonCodes, and the contributing factors[] — the full audit trail of the four stages above.

flowchart LR
  R["1 Retrieval
pg_trgm (+ phonetic / nickname)"] --> C["2 Classification
name x DoB"]
  C --> CL{"TruePositive /
PotentialMatch /
FalsePositive"}
  CL -- "real only" --> S["3 Scoring
0-100 + band"]
  S --> D["4 Decision
matrix -> Pass / Review / Fail"]
  D --> OUT["5 Return
score, riskScore, riskBand,
decision, reasonCodes, factors[]"]
      

2 · The 0–100 risk score

Only real matches feed the score — TruePositive or PotentialMatch. A warning type the tenant has switched off is dropped before scoring, as if the hit never happened. Each surviving match contributes:

flowchart LR
  M["Real matches only
(TruePositive / PotentialMatch,
enabled warning types)"] --> C["contribution =
categoryWeight x countryWeight x matchConfidence"]
  C --> MAX["aggregate = MAX single contribution
(the worst hit governs, not the sum)"]
  MAX --> N["normalize: a full-confidence,
weight-1.0 match = the tenant's High threshold"]
  N --> S["clamp 0-100 -> riskScore"]
      

• matchConfidence — the provider name-match score, clamped to 0–1.
• categoryWeight — the tenant's weight for the match's canonical category (sanctions / pep / adverse_media); criminal-category hits use the dedicated CriminalWeight.
• countryWeight — the tenant's weight for the matched entity's nationality.

Banding

The score is bucketed against three tenant-configured thresholds (defaults shown):

3 · Classification & evidence tiers

Name strength is judged by the fuzzy name scorer. A name whose confidence reaches the near-exact bar (NearExactNameSimilarity = 0.97) is treated as an exact / near-identical name; anything below it is a weaker, partial overlap. That name signal is then combined with the date-of-birth signal — a corroborated full-DoB agreement, a full DoB that mismatches beyond tolerance, or no usable DoB — to place a real match into one of four evidence tiers. The tier is the row dimension of the decision matrix in §4.

4 · The decision matrix

Each real, enabled match gets a base decision from an explicit matrix keyed by category × evidence-tier × multiplicity (single vs 2+ real matches). The authoritative outcome is the strongest base decision across all matches — precedence is always Fail > Review > Pass — after which the band policy and floors apply. Two structural invariants keep the matrix regulatorily safe: a watchlist cell (sanctions / criminal) can never resolve to Pass, and a Multiple cell is never softer than its Single sibling (2+ matches can only hold or escalate).

The shipped default grid (identical for single and multiple), where P is the tenant's unconfirmed-hit posture SanctionsUnconfirmedDecision — Review by default, Fail for a strict tenant:

The rules the default cells encode, and the floors applied on top of the aggregate:

Review-policy modifiers

When the aggregate is Review (nothing forced a Fail), two tenant flags can move it — but an unconfirmed watchlist hit is always floored back to Review, never quietly Passed:

5 · A worked example you can reproduce

To keep this honest and reproducible we screen a well-known sanctioned public figure (Bashar al-Assad — on the actual OFAC / EU / UK lists, a public watchlisted subject, not a private individual) against the live sandbox. Two curl calls; run them and you get the same shape.

# 1 - register a throwaway sandbox tenant; copy the aml_test_ key from the response into AML_KEY
curl -s -X POST https://aml-screening.dloizides.com/v1/register \
  -H "Content-Type: application/json" \
  -d '{"companyName":"Docs Example","email":"you@example.com"}'
export AML_KEY="aml_test_the-key-from-step-1"

# 2 - screen a subject that hits a sanctions entry
curl -s -X POST https://aml-screening.dloizides.com/v1/screenings/check \
  -H "X-Api-Key: $AML_KEY" \
  -H "Content-Type: application/json" \
  -d '{"fullName":"Bashar al-Assad"}'

The real response (captured 2026-08-09, abridged to the fields that matter):

{
  "isMatch": true,
  "score": 1,
  "classification": "PotentialMatch",
  "riskScore": 85,
  "riskBand": "High",
  "decision": "Fail",
  "matchedEntities": [
    { "sourceList": "UK",       "matchedName": "Bashar AL ASSAD",  "score": 1, "classification": "PotentialMatch", "rejectionTag": "sanctions" },
    { "sourceList": "EU",       "matchedName": "Bashar AL-ASSAD",  "score": 1, "classification": "PotentialMatch", "rejectionTag": "sanctions" },
    { "sourceList": "OFAC",     "matchedName": "Bashar AL-ASSAD",  "score": 1, "classification": "PotentialMatch", "rejectionTag": "sanctions" },
    { "sourceList": "WIKIDATA", "matchedName": "Bashar al-Assad",  "score": 1, "classification": "PotentialMatch", "rejectionTag": "pep" }
  ],
  "factors": [
    { "category": "sanctions", "sourceList": "UK",       "country": "Syria", "contribution": 1 },
    { "category": "sanctions", "sourceList": "EU",       "country": null,    "contribution": 1 },
    { "category": "sanctions", "sourceList": "OFAC",     "country": "Syria", "contribution": 1 },
    { "category": "pep",       "sourceList": "WIKIDATA", "country": "Syria", "contribution": 1 }
  ]
}

Stepping the real numbers through §2–§4:

6 · What's tenant-configurable

Every number and branch above is per-tenant configuration (RiskProfileConfig + WarningTypeConfig + the matching profile), not a fixed constant: