Scoring & decisioning — how a screen becomes a decision

This is the authoritative page for how PROOViD AML turns a name you submit into a match classification and a 0–100 risk score and band, and §5 is a worked example you can reproduce yourself with two curl calls. The companion page Decision rules is the single source of truth for the rules that resolve those matches to Pass / Review / Fail — the full decision matrix, the named rules, the floors, Enhanced Due Diligence and the decisioning knobs. Nothing here is a black box: every number and every branch is drawn straight from the scoring engine. 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

Two name bars, two different questions

Name strength is judged by the fuzzy name scorer against two separate bars, and they do not answer the same question. Conflating them is the difference between surfacing a hit for a human and rejecting a customer automatically:

The five evidence tiers

The name signal is combined with the date-of-birth signal — a corroborated full-DoB agreement, two full DoBs that differ but stay inside tolerance, a full DoB that mismatches beyond tolerance, or no usable DoB — to place a real match into one of five evidence tiers. The tier is the row dimension of the decision matrix, which is tabulated in full in Decision rules §3. Note which tiers require the name bar to be cleared and which do not:

4 · From score to decision

Each real, enabled match gets a base decision from an explicit matrix keyed by category × evidence tier × multiplicity (single vs 2+ real matches) — four categories × the five tiers of §3 × two multiplicities, 40 cells in all. The authoritative outcome is the strongest base decision across all matches — precedence is always Fail > Review > Pass — after which the floors, the band policy and the post-screening Enhanced Due Diligence check apply.

Three structural invariants hold whatever a tenant configures — a misconfiguration cannot breach them:

1. A watchlist hit never auto-clears. A sanctions / criminal cell can never resolve to Pass; a Pass override on one is raised to Review.
2. Multiplicity never lowers. A Multiple cell is never softer than its Single sibling — 2+ matches can only hold or escalate.
3. A Fail requires an exact name. If the matched name does not clear the tenant's ExactNameSimilarity bar (§3), a resolved Fail is clamped to Review, with NAME_NOT_EXACT recorded so the downgrade is never silent.

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://wl.proovid.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://wl.proovid.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 in the score

Every number in §2 is per-tenant configuration (RiskProfileConfig + the matching profile), not a fixed constant. These are the knobs that move the score and the band: