> ## Documentation Index
> Fetch the complete documentation index at: https://docs.gominerva.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Match Scoring Guide
> How to configure screening thresholds, candidate scoring weights, matching behavior, News retrieval, entity resolution, and score simulations across Minerva workflows.
export const StorybookFrame = ({storyId, title, version = "20260419-1", height, zoom = 0.7, preferLocalPreview = false}) => {
const HOSTED_STORYBOOK_BASE_URL = "https://minerva-storybook.s3.ca-central-1.amazonaws.com/iframe.html";
const isLocalDocsPreview = typeof window !== "undefined" && ["localhost", "127.0.0.1"].includes(window.location.hostname);
const storybookBaseUrl = preferLocalPreview && isLocalDocsPreview ? "http://localhost:6006/iframe.html" : HOSTED_STORYBOOK_BASE_URL;
const params = new URLSearchParams({
id: storyId,
viewMode: "story",
singleStory: "true",
shortcuts: "false",
toolbar: "0",
nav: "0",
panel: "0"
});
params.set("v", version);
const src = `${storybookBaseUrl}?${params.toString()}`;
const unscaledHeight = `${Math.ceil(height / zoom)}px`;
const unscaledWidth = `${100 / zoom}%`;
return ;
};
Match scoring controls how broadly or narrowly Minerva keeps potential screening matches as they move through candidate retrieval, entity resolution, and final result filtering.
**Access:** Requires the Admin role or above. In the
sidebar, go to Administration > Configuration,
then open Match scoring under Screening behaviours.
Use this guide when you need to:
* choose between the built-in Balanced, Narrow, and Wide presets
* tune one screening channel without changing the other channels
* adjust pre-resolution and post-resolution score thresholds
* control how much name, alias, date, location, identifier, occupation, gender, email, phone, and notes evidence contribute to candidate scoring
* control how missing optional evidence affects the score denominator
* tune name, DOB/date, location, and entity-resolution merge behavior
* tune News geography, News name filtering, article volume, and News location inference
* use the score simulator before saving changes
* review, audit, or roll back match scoring deployments
Balanced is the default Match Scoring configuration for every
workspace. It preserves Minerva's legacy scoring posture unless your workspace
has explicitly changed the settings.
Match scoring changes affect which candidates analysts see. Tune in small
increments, use clear change descriptions, and compare review volume, latency,
and missed-risk sensitivity before moving further away from Balanced.
## How Match Scoring Works
Every screening result passes through three broad stages:
1. Candidate retrieval: Minerva gathers source records from the
selected feeds.
2. Pre-resolution scoring: each source candidate is scored
against the searched subject before entity resolution.
3. Post-resolution scoring: Minerva clusters likely duplicate
source records, scores the resolved candidate, and filters the final returned
result set.
The Match Scoring configuration controls the second and third stages through:
* Decision thresholds: feed-specific pre-resolution thresholds
and one post-resolution threshold.
* Candidate score weights: how much each evidence category
contributes when it is present.
* Candidate gates: minimum name and Sanctions/PEP cutoffs that
can stop candidates before other evidence helps.
* Name matching behavior: tolerance for transposed names,
initials, phonetics, hyphenation, extra name parts, and organization base/full
names.
* DOB/date matching behavior: soft date falloff, hard date
cutoffs, and inferred-date confidence handling.
* Location matching behavior: default strictness, component
cutoff, and whether nationality can satisfy country matching.
* Entity-resolution merge behavior: merge thresholds and strong
organization merge shortcut settings.
* News controls: geography filter, name filter, article cap,
and article-location inference before News match scoring.
The configuration is workflow-specific and workspace-scoped. A Calibration workspace can test settings without changing Live until a workspace preset is promoted.
| Workflow | What it covers | Typical tuning posture |
| ----------------------------------- | ----------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------- |
| Onboarding | Profile creation and first-pass screening before a customer relationship is active. | Usually stricter because analysts are deciding whether to accept a new profile. |
| Ongoing monitoring | Repeated monitoring screens for existing profiles. | Usually conservative because changes can affect recurring alert volume across many profiles. |
| Direct API calls | API-driven screening submissions. | Often tuned for partner or reseller integrations. Workspace defaults are preferred, but request-level overrides remain supported. |
| Risk assessments | One-off risk-assessment searches in the app. | Often broader because analysts expect to inspect evidence directly in an investigation flow. |
## Channel Tabs And Copying Settings
Each workflow is configured on its own tab. The tab navigation stays visible as you scroll so you can see which channel you are changing.
Use the channel actions when you need to keep channels aligned:
| Action | What it does | When to use it |
| ------------------------------------------ | ---------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------- |
| Copy from another channel | Replaces the current channel with the selected source channel. | Use when onboarding and monitoring should share a posture, or when direct API should start from risk assessment settings before a small adjustment. |
| Apply this channel to all | Copies the active channel to every other channel. | Use after validating a complete channel configuration in Calibration and deciding the same settings should apply everywhere. |
| Workspace presets | Save a custom draft as a reusable workspace preset, update a workspace preset, or promote it between workspaces. | Use for repeatable operating modes, such as a stricter monitoring preset or a broader investigation preset. |
Start from the channel with the clearest calibration evidence. Copy it only
after you have compared representative true positives, false positives, and
high-volume cases in the simulator or a Calibration workspace.
## Finding Specific Settings
The page includes a setting finder and the Minerva command palette also indexes
the Match Scoring controls.
| Method | How to use it | What happens |
| ------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------- |
| Page setting finder | Search within the Match Scoring page for terms such as phonetics, DOB, missing evidence, merge threshold, or News article limit. | The page filters or jumps to matching controls so an admin does not need to scan every section. |
| Command palette | Open the command palette and search for a setting name or common variant, such as transposition, sound alike, person name cutoff, location strictness, or score simulator. | Minerva opens Match Scoring and highlights the requested control with a brief yellow flash. |
Use the command palette when you already know the setting you need. Use the page
finder when you are comparing nearby settings inside the same section.
## Understanding Scores
Minerva uses normalized match scores from 0.00 to 1.00.
* 1.00 means the compared values are effectively exact matches.
* Values closer to 1.00 are stronger matches.
* Values closer to 0.00 are weaker matches.
* A threshold is the minimum score required to keep the candidate at that stage.
In result details and API responses, field-level criteria match labels are interpreted as:
| Label | Score range | Meaning |
| ---------------------- | ---------------------------------------------------- | ----------------------------------------------------- |
| Exact | 0.98 and above | The field is effectively exact. |
| Close | 0.85 to below 0.98 | The field is strongly similar, but not exact. |
| Loose | 0.75 to below 0.85 | The field is a weaker fuzzy match. |
| None | Below 0.75 | The field does not provide meaningful match evidence. |
The overall candidate score is not a simple average of the visible field labels. The engine scores the candidate using weighted evidence, candidate gates, missing-evidence behavior, and stage-specific thresholds.
## Built-In Presets
Minerva includes three built-in presets. Built-in presets stay fixed, and workspace presets can be created from a custom draft.
| Preset | Best for | Main behavior |
| ------------------------- | --------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------- |
| Balanced | Default production posture. | Preserves legacy defaults for customers that do not change match scoring. |
| Narrow | Reducing borderline matches and review volume. | Raises thresholds, strengthens identity/date/location evidence, and applies stricter date/location/merge behavior. |
| Wide | Calibration reviews, higher-risk cohorts, or investigations where recall matters more than review volume. | Lowers thresholds, broadens News filtering, makes name/date/location matching more tolerant, and lowers merge thresholds. |
### Preset Thresholds
Decision thresholds are editable from 0.60 to 1.00.
| Preset | Workflow | Sanctions pre-resolution | PEP pre-resolution | News pre-resolution | Post-resolution |
| -------- | ------------------ | -----------------------: | -----------------: | ------------------: | --------------: |
| Balanced | Onboarding | 0.85 | 0.85 | 0.85 | 0.85 |
| Balanced | Ongoing monitoring | 0.85 | 0.85 | 0.85 | 0.85 |
| Balanced | Direct API calls | 0.75 | 0.75 | 0.70 | 0.70 |
| Balanced | Risk assessments | 0.75 | 0.75 | 0.70 | 0.70 |
| Narrow | Onboarding | 0.90 | 0.90 | 0.90 | 0.90 |
| Narrow | Ongoing monitoring | 0.90 | 0.90 | 0.90 | 0.90 |
| Narrow | Direct API calls | 0.85 | 0.85 | 0.80 | 0.80 |
| Narrow | Risk assessments | 0.85 | 0.85 | 0.80 | 0.80 |
| Wide | Onboarding | 0.75 | 0.75 | 0.75 | 0.75 |
| Wide | Ongoing monitoring | 0.75 | 0.75 | 0.75 | 0.75 |
| Wide | Direct API calls | 0.65 | 0.65 | 0.60 | 0.60 |
| Wide | Risk assessments | 0.65 | 0.65 | 0.60 | 0.60 |
### Preset Retrieval And Runtime Summary
| Preset | News geography | News name filter | Max requested articles | Location inference | Default location strictness | Merge thresholds |
| -------- | -------------- | ---------------- | ---------------------: | ------------------ | --------------------------- | ------------------------------------- |
| Balanced | Strict | Strict | 300 | Off | No default | AI-assisted 0.66, exact-evidence 0.66 |
| Narrow | Strict | Strict | 200 | Off | City | AI-assisted 0.72, exact-evidence 0.72 |
| Wide | Broad | Broad | 600 | Off | No default | AI-assisted 0.60, exact-evidence 0.60 |
## Decision Thresholds
Pre-resolution and post-resolution thresholds answer different questions.
| Threshold | Stage | What increasing does | What decreasing does |
| ----------------------------------------- | ------------------------ | ----------------------------------------------------------------- | ----------------------------------------------------------------------------------------- |
| Sanctions pre-resolution | Before entity resolution | Fewer weak sanctions source records continue into resolution. | More borderline sanctions records can continue and potentially merge with other evidence. |
| PEP pre-resolution | Before entity resolution | Fewer weak PEP source records continue into resolution. | More borderline PEP records can continue and potentially merge with other evidence. |
| News pre-resolution | Before entity resolution | Fewer weak adverse-media source records continue into resolution. | More borderline News records can continue and potentially merge with other evidence. |
| Post-resolution | After entity resolution | Final analyst-visible results become narrower. | Lower-scoring resolved candidates can remain visible. |
If weak records are obviously not related to the searched subject, tune the
feed-specific pre-resolution threshold first. If records look related before
entity resolution but disappear after final scoring, tune the post-resolution
threshold.
## Candidate Score Weights
Candidate score weights control how much each evidence category contributes when that evidence is present. The dashboard presents the main control once per setting and applies it to both stages. Use Advanced: split pre/post resolution only when a channel needs different behavior before and after entity resolution.
Most evidence-weight sliders use a customer-facing range of 0.00 to 1.00. The Missing evidence penalty uses 0 to 100.
| Group | Setting | What it affects | Balanced pre | Balanced post | Tuning guidance |
| ------------------- | ------------------------------ | --------------------------------------------------------------- | -----------: | ------------: | ------------------------------------------------------------------------------------------------------------------------------------ |
| Identity evidence | Primary name | Main searched-subject name compared with the candidate name. | 1.00 | 1.00 | Keep high for most workflows. Lower only when other evidence is highly reliable and names vary substantially. |
| Identity evidence | Aliases | Known alternate names on the potential match. | 0.98 | 0.98 | Raise when aliases are reliable and important; lower if alias lists create common-name noise. |
| Identity evidence | Identifiers | Government, registration, and other identifier evidence. | 0.05 | 0.05 | Increase when identifiers are normalized and trusted. Keep lower when identifiers are often partial or absent. |
| Profile context | Location | Country, state, city, address, and nationality evidence. | 0.10 | 0.75 | Higher values separate similar names by geography. Lower values are broader when locations are incomplete or inconsistent. |
| Profile context | DOB / date | Birth date, incorporation date, or formation date. | 0.10 | 0.50 | Higher values make date agreement more decisive. Lower values are broader when dates are often missing, partial, or inferred. |
| Profile context | Occupation | Role, job title, or organization relationship evidence. | 0.10 | 0.01 | Increase when role data reliably distinguishes matches. Keep lower when role data is sparse or inconsistently sourced. |
| Profile context | Gender | Gender evidence when present on both records. | 0.05 | 0.05 | Use carefully because gender data can be missing or inconsistently reported. |
| Supporting evidence | Email | Email address overlap between candidate and match. | 0.05 | 0.05 | Increase when email is a trusted identifier for the workflow. |
| Supporting evidence | Phone | Phone number overlap between candidate and match. | 0.05 | 0.05 | Increase when phone data is trusted and not commonly shared or recycled. |
| Supporting evidence | Notes | Customer-supplied notes and narrative evidence. | 0.05 | 0.05 | Increase only when notes are consistently structured and reliable. |
| Score behavior | Candidate score pass threshold | Internal candidate-score pass threshold for the selected stage. | 0.70 | 0.70 | Higher values filter candidates earlier in the scoring stage. This is separate from public result thresholds. |
| Score behavior | Missing evidence penalty | How strongly unavailable optional evidence lowers the score. | 5 | 10 | A value of 0 disables the missing-evidence penalty. Larger values penalize records with unavailable optional evidence more strongly. |
Missing evidence penalty is safe to turn off. A value of
0 means missing optional fields do not reduce the
denominator. For example, if the request includes name and DOB, and the
candidate matches the name but has no DOB to compare, the DOB absence does not
reduce the score when the missing-evidence penalty is 0.
### Candidate Weight Preset Values
| Setting | Balanced pre/post | Narrow pre/post | Wide pre/post |
| ------------------------------ | ----------------- | --------------- | ------------- |
| Primary name | 1.00 / 1.00 | 1.00 / 1.00 | 1.00 / 1.00 |
| Aliases | 0.98 / 0.98 | 0.98 / 0.98 | 0.98 / 0.98 |
| Location | 0.10 / 0.75 | 0.25 / 1.00 | 0.05 / 0.50 |
| DOB / date | 0.10 / 0.50 | 0.20 / 0.80 | 0.05 / 0.30 |
| Occupation | 0.10 / 0.01 | 0.10 / 0.01 | 0.10 / 0.01 |
| Gender | 0.05 / 0.05 | 0.05 / 0.05 | 0.05 / 0.05 |
| Notes | 0.05 / 0.05 | 0.05 / 0.05 | 0.05 / 0.05 |
| Email | 0.05 / 0.05 | 0.05 / 0.05 | 0.05 / 0.05 |
| Phone | 0.05 / 0.05 | 0.05 / 0.05 | 0.05 / 0.05 |
| Identifiers | 0.05 / 0.05 | 0.05 / 0.05 | 0.05 / 0.05 |
| Candidate score pass threshold | 0.70 / 0.70 | 0.78 / 0.80 | 0.60 / 0.60 |
| Missing evidence penalty | 5 / 10 | 10 / 20 | 2.5 / 4 |
## Candidate Gates
Candidate gates are cutoffs that can stop a candidate before weighted evidence alone determines the score.
| Setting | Range | Balanced | Narrow | Wide | What increasing does |
| ----------------------------- | ------------ | -------: | -----: | ---: | ------------------------------------------------------------------------------ |
| Person name cutoff | 0.00 to 1.00 | 0.50 | 0.60 | 0.35 | Person candidates need stronger name evidence before other signals can help. |
| Organization name cutoff | 0.00 to 1.00 | 0.80 | 0.88 | 0.70 | Organization candidates need closer name similarity before continuing. |
| Sanctions/PEP cutoff | 0.00 to 1.00 | 0.75 | 0.82 | 0.65 | Sanctions and PEP candidates need stronger total evidence before continuing. |
| Sanctions/PEP location weight | 0.00 to 1.00 | 0.05 | 0.10 | 0.02 | Location agreement has more influence for Sanctions and PEP candidate scoring. |
Some legacy backend fields remain available for API compatibility but are not
shown in the dashboard. Customer-facing configuration should use the settings
above.
## Name Matching Behavior
Name matching behavior controls how the engine converts compared names into name similarity scores before the name weight is applied.
### Person Names
| Setting | Range | Balanced | Narrow | Wide | What it controls |
| ------------------------- | ------------ | -------: | -----: | ---: | --------------------------------------------------------------------------------------------------------------- |
| Transposition tolerance | 0.00 to 1.00 | 0.9425 | 0.90 | 0.97 | How much name-part transposition affects similarity, such as given and family names appearing in reverse order. |
| Initials tolerance | 0.00 to 1.00 | 0.80 | 0.70 | 0.90 | How initials are treated when compared with full given, middle, or family-name parts. |
| Extra name penalty | 0.00 to 1.00 | 0.05 | 0.08 | 0.02 | How strongly unmatched extra name parts reduce similarity. |
| Text similarity floor | 0.00 to 1.00 | 0.05 | 0.08 | 0.02 | Minimum spelling similarity needed before phonetic matching can help. |
| Phonetics tolerance | 0.00 to 1.00 | 0.815 | 0.75 | 0.90 | How much Double Metaphone-style sound-alike similarity can preserve score when spellings differ. |
| Length difference weight | 0.00 to 1.00 | 0.70 | 0.80 | 0.50 | How strongly large name-length differences reduce similarity. |
| Hyphenated name tolerance | 0.00 to 1.00 | 0.98 | 0.95 | 1.00 | How hyphenated names and expanded variants compare, such as Smith-Jones and Smith Jones. |
Use higher tolerance values when the workflow should accept common formatting, transliteration, phonetic, and ordering variation. Use lower tolerance values when name precision matters more and broader recall is creating too many same-name matches.
### Organization Names
| Setting | Range | Balanced | Narrow | Wide | What it controls |
| ---------------- | ------------ | -------: | -----: | ---: | ------------------------------------------------------------------------------------------------------------- |
| Base name weight | 0.00 to 1.00 | 0.75 | 0.80 | 0.65 | How much the normalized base organization name contributes after common suffixes and descriptors are reduced. |
| Full name weight | 0.00 to 1.00 | 0.25 | 0.20 | 0.35 | How much the full organization name contributes, including suffixes, descriptors, and trading-name text. |
Raise base name weight when legal suffixes, punctuation, and descriptors vary frequently. Raise full name weight when exact full-name agreement should matter more.
## DOB And Date Matching Behavior
DOB/date behavior controls how date evidence is scored before the DOB/date weight is applied.
| Setting | Range | Balanced | Narrow | Wide | What it controls |
| ----------------------------------------- | ------------------- | -------: | ------: | ------: | --------------------------------------------------------------------------------------------------------------- |
| Person DOB soft match falloff days | 1 to 36500 days | 730 | 365 | 1825 | How quickly person DOB similarity decays as dates move apart. |
| Person DOB hard range cutoff years | 0 to 500 years | 500 | 10 | 500 | Maximum person DOB gap that can receive any date similarity. Beyond this range, date similarity is forced to 0. |
| Organization date soft match falloff days | 1 to 36500 days | 3650 | 1825 | 7300 | How quickly organization date similarity decays as incorporation or formation dates move apart. |
| Organization date hard range cutoff years | 0 to 500 years | 500 | 20 | 500 | Maximum organization date gap that can receive any date similarity. |
| High inferred date confidence | 0.00 to 1.00 | 0.95 | 0.95 | 0.95 | Contribution for high-confidence inferred date evidence when exact date is unavailable. |
| Low inferred date confidence | 0.00 to 1.00 | 0.30 | 0.40 | 0.20 | Contribution floor for low-confidence inferred date evidence. |
| Normal inferred date range years | 0.10 to 100 years | 2 | 1 | 5 | Year range allowed around normally inferred dates. |
| Low confidence date range years | 0.10 to 100 years | 20 | 10 | 30 | Year range allowed around low-confidence inferred dates. |
| Apply inferred date confidence weighting | Enabled or disabled | Enabled | Enabled | Enabled | Whether lower-confidence inferred dates contribute less than higher-confidence inferred dates. |
The soft falloff is not a pass/fail boundary. It changes the shape of date-score decay for dates within the hard range cutoff. The hard cutoff is the boundary where date similarity becomes 0 before weighting.
## Location Matching Behavior
Location matching behavior controls how location evidence is evaluated before the location weight is applied.
| Setting | Values / range | Balanced | Narrow | Wide | What it controls |
| ----------------------------------- | ---------------------------------------------------- | ---------- | -------- | ---------- | ------------------------------------------------------------------------------------------------------ |
| Default location strictness | No default, Country, State / province, City, Address | No default | City | No default | Minimum location level required when a request does not provide its own strictness. |
| Strict location cutoff | 0.00 to 1.00 | 0.80 | 0.90 | 0.65 | Minimum component score when strict location matching is active. |
| Allow nationality for country match | Enabled or disabled | Enabled | Disabled | Enabled | Whether nationality can satisfy country-level matching when country evidence is missing or incomplete. |
Strictness levels are progressive:
| Strictness | Matching behavior |
| ---------------- | -------------------------------------------------------------------------------------------------------- |
| No default | Location details are scored, but no minimum location level is required unless the request sets one. |
| Country | Requires country agreement when both sides provide country evidence. Nationality can count when enabled. |
| State / province | Requires country and state/province agreement when both sides provide those details. |
| City | Requires country, state/province, and city agreement when both sides provide those details. |
| Address | Requires all available location levels, including street address, to agree closely enough. |
## Entity-Resolution Merge Behavior
Entity resolution combines likely duplicate source records before post-resolution scoring. Merge settings affect candidate clustering, not the final score threshold directly.
| Setting | Range | Balanced | Narrow | Wide | What increasing does |
| --------------------------------- | ------------------- | -------: | ------: | ------: | ------------------------------------------------------------------------------------------------ |
| AI-assisted merge threshold | 0.00 to 1.00 | 0.66 | 0.72 | 0.60 | Automatic AI-assisted merges become stricter, reducing accidental merges. |
| Exact-evidence merge threshold | 0.00 to 1.00 | 0.66 | 0.72 | 0.60 | Rule-based or exact-evidence merges require stronger agreement. |
| Enable strong organization merges | Enabled or disabled | Enabled | Enabled | Enabled | Allows highly similar organization records to use the strong organization shortcut. |
| Strong organization name cutoff | 0.00 to 1.00 | 0.88 | 0.92 | 0.82 | Strong organization shortcut merges require closer organization-name agreement. |
| Strong organization date days | 0 to 36500 days | 31 | 14 | 90 | Strong organization shortcut merges tolerate larger incorporation or formation-date differences. |
| Strong organization confidence | 0.00 to 1.00 | 1.00 | 1.00 | 0.90 | Shortcut merges are recorded with higher confidence. |
Raise merge thresholds when unrelated source records are being combined. Lower them when duplicate records are staying separate and creating repeated analyst review.
## News Controls For Adverse Media
Each screening workflow has its own News controls. These settings sit before final match scoring. They change which articles are retrieved, which retrieved articles are admitted for adverse-media analysis, and whether article-linked locations are added before geography scoring.
Broadening News retrieval can increase adverse-media volume and processing
time. Avoid changing geography bias, name filtering, article caps, and score
thresholds all at once unless you are running a controlled calibration pass.
| Setting | Values / range | Balanced | Narrow | Wide | Main effect |
| --------------------------------- | ------------------- | -------- | -------- | -------- | -------------------------------------------------------------------------------------------------------------------- |
| News geography filter | Strict, Broad, None | Strict | Strict | Broad | Controls how subject geography is applied by the News retrieval filter before match scoring. |
| News name filter | Strict, Broad | Strict | Strict | Broad | Controls how subject names are matched by the News retrieval filter before match scoring. |
| Max requested articles | 100 to 750 | 300 | 200 | 600 | Caps how many News article candidates are reviewed for article matching, sentiment scoring, and risk classification. |
| Infer article locations from News | Enabled or disabled | Disabled | Disabled | Disabled | Reviews matching News articles for subject-linked geography before News geography scoring. |
### News Geography Filter
| Setting | Retrieval behavior | When to use it |
| ------- | ----------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------- |
| Strict | Uses exact subject-name retrieval and applies city/state terms when available. Country-only searches do not add a geography clause. | Use as the default for common names and high-volume workflows. |
| Broad | Uses broader city/state matching with optional country expansion when location evidence is available. | Use when relevant articles often mention only a wider region or country. |
| None | Searches without geography terms. | Use for targeted investigations where location evidence is weak or misleading and analysts expect more review volume. |
### News Name Filter
| Setting | Matching behavior | When to use it |
| ------- | --------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------ |
| Strict | Requires exact-name evidence in trusted article fields before News records continue to scoring. | Use for common names, high-volume monitoring, and workflows where precision matters more than recall. |
| Broad | Allows bounded token-proximity matches, minor name variation, middle-name expansion, hyphenation differences, and trusted snippet or quote matches. | Use when subjects are often reported with middle names, transliteration variants, entity suffix differences, or reliable partial snippets. |
### Max Requested Articles
Raise this value when relevant adverse-media articles may appear later in provider results. Lower it when common-name searches are creating too much latency or when a workflow does not need broad article recall.
Higher article caps can add processing time because Minerva may retrieve and
review more News candidates. High-volume subjects may take a few additional
seconds for each extra 100 articles, especially when retrieval has also been
broadened.
### News Location Inference
News location inference reviews matching risk-classified News articles and extracts locations that appear tied to the screened subject. Those inferred article locations can then provide more geographic evidence before News match scoring.
Turn it on when article text often identifies the subject's relevant city, state, region, country, operations, arrest, investigation, or other subject-linked geography more clearly than the original search request.
News location inference uses model-backed article analysis and can add seconds
to News searches. Enable it first in Calibration, direct API, or
risk-assessment workflows where the extra geographic evidence is worth the
added latency before considering it for high-volume monitoring.
## Score Simulator
The score simulator lets administrators test the current draft channel settings against an editable example without creating a live search or writing screening results.
Use it when you want to answer questions like:
* Would this exact-name, missing-DOB candidate still pass if missing evidence is penalized more?
* How much does a different city or country reduce the score?
* Would a transposed or phonetic name variation pass under Narrow, Balanced, or Wide?
* Does the pre-resolution score behave differently from the post-resolution score?
* Which setting moved the score enough to pass or fail the selected threshold?
### How To Use The Simulator
1. Select the workflow tab you want to test, such as Onboarding or Direct API calls.
2. Adjust the draft settings or select a preset. You do not need to save first.
3. Go to Score simulator.
4. Choose Pre-resolution or Post-resolution under Score using.
5. Edit the Screened profile. Include the subject type, name, date, location, and screening sources that represent the request.
6. Edit the Potential match record. Include the candidate name, aliases, date, locations, country, nationality, occupation/role, source lists, and feed hits you want to compare.
7. Click Run simulation.
8. Review the resulting score, return/filter state, threshold comparison, and attribute comparison.
Run the same example before and after changing one setting. This makes it
easier to see whether the score moved because of a threshold, a field weight,
missing evidence, name behavior, date behavior, or location behavior.
### Reading Simulation Results
| Result area | How to interpret it |
| -------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Overall score | The simulated candidate score under the selected workflow and stage. |
| Passed / failed | Whether the score meets the selected threshold and gates for that stage. |
| Threshold snapshot | The pre-resolution or post-resolution thresholds used for the run. |
| Attribute comparison | Field-level comparison scores such as name, aliases, date, city, state, and country. |
| Tested fields | The screened-profile and potential-match fields captured in simulator history. |
| Simulation history | Recent simulator runs can be reviewed so teams can connect save decisions to examples they tested. Saved changes can link back to the simulations reviewed before deployment. |
Simulator results are examples, not production searches. They are best used for calibration and explanation before saving changes or promoting a workspace preset.
## Recommended Tuning Approach
Use this sequence when calibrating match scoring:
1. Start from Balanced and collect examples of false positives, plausible missed matches, and high-volume review cohorts.
2. Tune one workflow at a time. Onboarding, monitoring, Direct API, and risk assessments often have different tolerance for review volume.
3. Use the simulator to compare representative examples before saving.
4. Adjust feed-specific pre-resolution thresholds when the issue is feed-specific noise.
5. Adjust post-resolution thresholds when entity resolution is grouping candidates correctly but the final result set is too broad or too narrow.
6. Adjust candidate score weights only when the field-level evidence balance is wrong. For example, increase location or DOB/date weights when similar names are passing despite conflicting location or date evidence.
7. Adjust name, DOB/date, and location behavior when the field similarity score itself is too strict or too forgiving.
8. Adjust merge thresholds when entity resolution is over-merging or under-merging source records.
9. Tune one adverse-media retrieval control at a time. Moving geography bias from Strict to Broad or None, turning on Broad name filtering, or raising max requested articles changes the upstream article pool, not only the final score filter.
10. Enable News location inference only where the extra subject-linked geography is worth the added latency.
11. Save a clear change description so history shows why the calibration was deployed.
12. Use history and rollback if the change moves review volume, latency, or recall in the wrong direction.
General tuning guidance:
* higher public thresholds are stricter and usually reduce analyst-visible matches
* lower public thresholds are broader and usually increase recall and review volume
* higher evidence weights make that evidence category more influential when present
* a higher missing-evidence penalty makes unavailable optional evidence reduce scores more strongly
* higher name tolerance settings generally make name variations easier to match, while higher penalties or floors make name matching stricter
* lower merge thresholds reduce duplicate resolved candidates but increase over-merge risk
* higher article caps and News location inference can increase News search latency
* monitoring changes should be made carefully because they can change recurring alert volume across an existing profile population
* direct API changes should be coordinated with API consumers, especially if those consumers already submit request-level overrides
## Request-Level Overrides
Match scoring is the workspace default. It applies when the screening request does not provide an explicit override. This is the preferred operating model, especially for Direct API customers, because it keeps defaults visible in the dashboard and audit history.
Direct API requests can still override settings for partnership, reseller, legacy, or investigation-specific flows. Core screening logic gives request-level values precedence over workspace configuration.
For new integrations, use the same customer-facing ranges shown in the
dashboard tables. Some backend fields accept broader legacy ranges for backward
compatibility, but dashboard-equivalent values are easier to reason about,
audit, and compare with simulator runs.
| Override type | Preferred request field | Notes |
| ------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Canonical runtime object | `global_filters.match_scoring_runtime_config` | Nested object that mirrors the workspace runtime sections: `candidateScoring`, `nameMatching`, `dobMatching`, `locationMatching`, and `entityResolution`. |
| Feed pre-resolution threshold | `feed_filters.Sanctions.pre_resolution_match_threshold`, `feed_filters.PEP.pre_resolution_match_threshold`, `feed_filters.News.pre_resolution_match_threshold` | Feed-specific overrides take precedence for that feed. |
| Global pre-resolution threshold | `global_filters.pre_resolution_match_threshold` | Applies when a feed-specific threshold is not supplied. |
| Post-resolution threshold | `global_filters.post_resolution_match_threshold` | Controls the final returned result set for the request. |
| Legacy threshold | `match_threshold` | Legacy alias. It still takes precedence where supported, but new integrations should use stage-specific thresholds. |
| Evidence weights | Scalar aliases such as `nameWeight`, `postResolutionNameWeight`, `locationWeight`, `dobWeight`, `identifierWeight` | Aliases normalize into `candidateScoring.preResolutionWeights` and `candidateScoring.postResolutionWeights`. Shared aliases apply to both stages; stage-specific aliases override one stage. |
| Missing evidence penalty | `missingEvidencePenalty`, `preResolutionMissingEvidencePenalty`, `postResolutionMissingEvidencePenalty` | Customer-facing 0 to 100 scale. 0 disables the penalty. Larger values penalize missing optional evidence more. |
| Name behavior | `transpositionTolerance`, `initialsTolerance`, `extraNamePenalty`, `textSimilarityFloor`, `phoneticsTolerance`, `lengthDifferenceWeight`, `hyphenatedNameTolerance` | Scalar aliases normalize into `nameMatching.person`. |
| Organization-name behavior | `baseNameWeight`, `fullNameWeight` | Scalar aliases normalize into `nameMatching.organization`. |
| DOB/date behavior | `personDateWindowDays`, `personMaxDateToleranceYears`, `organizationDateWindowDays`, `organizationMaxDateToleranceYears`, inferred-date aliases | Scalar aliases normalize into `dobMatching`. |
| Location behavior | `defaultLocationStrictness`, `strictLocationCutoff`, `allowNationalityForCountryMatch` | Scalar aliases normalize into `locationMatching`. |
| Merge behavior | `aiAssistedMergeThreshold`, `exactEvidenceMergeThreshold`, `enableStrongOrganizationMerges`, `strongOrganizationNameCutoff`, `strongOrganizationDateDays` | Scalar aliases normalize into `entityResolution`. |
| News controls | `news_geography_bias`, `news_name_filter`, `max_requested_articles`, `news_location_inference` | Global or News feed-level values override workspace News settings for the request. |
If a request sends both a nested runtime object and scalar aliases, Minerva
merges them into one runtime configuration before scoring. Omitted sections
fall back to the workspace setting, then to Balanced defaults when no
workspace value exists.
Example Direct API override:
```json theme={null}
{
"global_filters": {
"post_resolution_match_threshold": 0.78,
"match_scoring_runtime_config": {
"candidateScoring": {
"preResolutionWeights": {
"name": 1,
"location": 0.25,
"time": 0.2,
"threshold": 0.78
},
"postResolutionWeights": {
"name": 1,
"location": 0.85,
"time": 0.7,
"threshold": 0.8
},
"gates": {
"individualNameMinimumContribution": 0.6,
"organizationNameMinimumScore": 0.88,
"sanctionsPepThresholdOverride": 0.82,
"sanctionsPepLocationWeightOverride": 0.1
}
},
"nameMatching": {
"person": {
"positionWeight": 0.9,
"initialsWeight": 0.7,
"phoneticsWeight": 0.75
}
},
"dobMatching": {
"individualDateStdevDays": 365,
"individualMaxDateToleranceYears": 10
},
"locationMatching": {
"defaultStrictness": "city",
"strictComponentCutoff": 0.9,
"allowCountryMatchFromNationality": false
},
"entityResolution": {
"mergeDecision": {
"modelConfidenceThreshold": 0.72,
"ruleBasedConfidenceThreshold": 0.72
}
}
}
},
"feed_filters": {
"Sanctions": {
"pre_resolution_match_threshold": 0.9
},
"PEP": {
"pre_resolution_match_threshold": 0.9
},
"News": {
"pre_resolution_match_threshold": 0.85,
"news_geography_bias": "strict",
"news_name_filter": "strict",
"max_requested_articles": 200
}
}
}
```
Scalar aliases are useful for legacy integrations, but the nested runtime object
is easier to audit because related settings stay grouped by scoring behavior.
## Role-Aware Adverse Media
Role-aware adverse media is a separate screening configuration that runs after adverse-media articles have been retrieved and analyzed. It helps identify whether a negative article appears to involve the screened subject or is likely only a name mention.
Use Match Scoring when you need to tune candidate thresholds, candidate evidence weighting, matching behavior, merge behavior, or News retrieval and article-analysis behavior. Use Role-Aware Adverse Media when you need to show or filter confident article-subject relevance signals after adverse-media analysis has already run.
For details, see the [Role-Aware Adverse Media Guide](/role-aware-adverse-media-guide).
## Reviewing And Confirming Changes
When you click Review changes, Minerva shows a grouped confirmation view before anything is saved.
The review dialog shows:
* the number of changes and sections affected
* the selected preset change, if applicable
* each workflow with changed thresholds, weights, gates, matching behavior, merge behavior, and News controls
* an optional Change Description field
* simulator examples linked to the draft, when available
Use the change description to capture the reason for the calibration, such as a false-positive review, a model calibration review, a high-risk cohort exception, or a post-launch monitoring adjustment.
## Deployment History And Rollback
The Match Scoring page includes a quick History drawer so you can preview recent deployments without leaving the configuration page.
Use the drawer to:
* see the current live deployment first
* review prior threshold, weight, matching behavior, merge behavior, and News retrieval changes
* preview an older deployment on the main page
* open the full audit history page
Rollback restores a previous deployment by writing a new history entry. It does not delete prior history.
The full history page includes:
* Changed: when the configuration was saved or rolled back
* Action: whether the event was an update or rollback
* Summary: the key scoring changes
* Changed by: the user who performed the change
* Actions: rollback entry points for older deployments
## Related Guides
* [Screening Guide](/screening-guide)
* [Repeated Alert Suppression Guide](/alert-suppression-guide)
* [Role-Aware Adverse Media Guide](/role-aware-adverse-media-guide)
* [Workspaces Guide](/workspaces-guide)
* [Bulk Actions Guide](/bulk-actions-guide)
* [Risk Assessment Flow](/risk-assessment-flow)