> ## Documentation Index
> Fetch the complete documentation index at: https://docs.didit.me/llms.txt
> Use this file to discover all available pages before exploring further.
# AML Match Score
> Learn how AML match scores measure identity confidence via name, DOB, and country matching. Tune weights and thresholds to cut false positives.
The **Match Score** is a weighted confidence metric that determines **how closely a potential AML match corresponds to the screened individual**. This score is used to classify individual matches as either **False Positives** or **Possible Matches** that require further review.
> ⚠️ **Important:** The Match Score determines **individual match classification**, NOT the final AML status. The final AML status (Approved/In Review/Declined) is determined by the [Risk Score](/core-technology/aml-screening/aml-risk-score) of non-false-positive matches.
## Overview
When screening a person against AML watchlists, each potential match receives a **match score from 0-100**. This score answers the question: **"Is this match actually the same person we're screening?"**
### Match Score vs Risk Score
| Aspect | Match Score | Risk Score |
| ------------- | ---------------------------------------------------- | ------------------------------------ |
| **Question** | Is this the same person? | How risky is this entity? |
| **Purpose** | Classify matches as False Positive vs Possible Match | Determine final AML status |
| **Factors** | Name, DOB, Country, Document Number | Country, Category, Criminal Records |
| **Threshold** | Match Score Threshold (default: 93) | Approve Threshold / Review Threshold |
***
## How Match Score Determines Review Status
Each match is classified based on its match score:
| Match Score | Review Status | Meaning |
| --------------------------------------- | ------------------ | ----------------------------------- |
| Score below Match Score Threshold | **False Positive** | Match is likely NOT the same person |
| Score at or above Match Score Threshold | **Unreviewed** | Match requires manual review |
> **Default threshold:** 93%
**Example:** With a threshold of 93:
* Match with score 85 → **False Positive** (auto-dismissed)
* Match with score 95 → **Unreviewed** (needs review, risk score determines urgency)
### Review Statuses Explained
All AML matches start with one of two initial statuses based on their match score:
| Status | Description | When Set |
| ------------------ | -------------------------------------------------------------------------------------------------- | ------------------------ |
| **False Positive** | The match is likely NOT the same person as the screened individual. Excluded from risk assessment. | Match score \< threshold |
| **Unreviewed** | The match is a possible match that requires manual review to confirm or dismiss. | Match score ≥ threshold |
After manual review, compliance officers can update the status to:
| Status | Description |
| ------------------- | ---------------------------------------------------- |
| **Confirmed Match** | The match has been verified as the same person. |
| **Inconclusive** | Unable to determine if the match is the same person. |
### **Tip:** You can change a match's review status in the Console by viewing the AML overview or clicking on a specific match to see its details.
***
## How the Match Score is Calculated
### Step 1: Base Score Calculation
The base score is calculated using three components with configurable weights:
```
Base Score = (Name Score × Name Weight) + (DOB Score × DOB Weight) + (Country Score × Country Weight)
```
| Component | Default Weight | Description |
| ----------------------- | -------------- | ------------------------------------------------------------ |
| **Name** | 60% | Fuzzy string similarity between screened name and match name |
| **Date of Birth** | 25% | Exact, partial (year only), or mismatch scoring |
| **Country/Nationality** | 15% | Comparison between screened nationality and match countries |
> **Note:** Weights must always sum to 100%.
### Step 2: Document Number "Golden Key" Logic
After calculating the base score, the document number is evaluated separately using special override logic:
| Scenario | Effect | Example |
| ----------------- | -------------------------- | --------------------------------------------- |
| **Match** | Override score to **100** | Passport numbers match exactly |
| **Neutral** | Keep base score unchanged | Different document types, or one side missing |
| **Hard Mismatch** | Apply penalty (-50 points) | Same document type but different values |
This approach recognizes that a matching document number is definitive proof of identity (the "Golden Key"), while mismatched document types shouldn't penalize the score.
***
## Component Scoring Details
### Name Similarity (0-100)
Name matching uses the **WRatio algorithm** from RapidFuzz, which is robust to:
* Typos and misspellings
* Word order differences ("John Smith" vs "Smith, John")
* Middle name variations ("Robert J. Smith" vs "Robert James Smith")
* Length differences
### Date of Birth Scoring
| Scenario | Score | Example |
| ------------------------------------ | --------------- | ----------------------------------------------------------------------------------------- |
| **Exact Match** | 100% | "1985-03-15" matches "1985-03-15" |
| **Year Match (match has year only)** | 100% | "1985-03-15" matches "1985" — full match because match only provides year-level precision |
| **Year Match (different day/month)** | 50% | "1985-03-15" matches "1985-06-20" — same year but dates differ |
| **Year Mismatch** | -100% (penalty) | "1985-03-15" does not match "1990-03-15" |
| **No Data** | 0% (neutral) | Either side missing DOB |
> **Important:** When the match only provides a year (e.g., "1974"), matching that year counts as a **full match** because that's all the information available to verify.
### Country/Nationality Scoring
| Scenario | Score | Example |
| -------------------- | -------------- | -------------------------------- |
| **Exact Match** | 100% | "ES" matches "Spain" or "ESP" |
| **No Data on Match** | 0% (neutral) | Match has no country information |
| **Mismatch** | -50% (penalty) | "ES" does not match "France" |
The system automatically converts between:
* ISO alpha-2 codes (ES)
* ISO alpha-3 codes (ESP)
* Full country names (Spain)
It also checks the `citizenship` field in addition to `countries`.
***
## Score Normalization (Re-weighting)
When data is missing from either the screened person or the match, the system uses **score normalization** to avoid penalizing for unavailable information.
### Example: Name-Only Screening
If you screen with only a name (no DOB or country):
| Original Weights | Normalized Weights |
| ---------------- | ---------------------------- |
| Name: 60% | Name: **100%** |
| DOB: 25% | DOB: 0% (not comparable) |
| Country: 15% | Country: 0% (not comparable) |
**Result:** The name score becomes the entire match score.
### Example: Missing Country on Match
If the match doesn't have country data but has DOB:
| Original Weights | Normalized Weights |
| ---------------- | ---------------------------- |
| Name: 60% | Name: **70.6%** |
| DOB: 25% | DOB: **29.4%** |
| Country: 15% | Country: 0% (not comparable) |
This ensures fair scoring regardless of data availability.
***
## Configuration Options
You can customize the match score calculation via the API or workflow settings:
### Match Score Threshold
| Setting | Default | Description |
| --------------------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------ |
| Match Score Threshold | 93 | Matches below this are classified as **False Positive**. Matches at or above are **Unreviewed** (Possible Matches) that need review. |
### Weights (must sum to 100)
| Setting | Default | Description |
| -------------- | ------- | -------------------------------------- |
| Name Weight | 60 | Weight for name similarity (0-100) |
| DOB Weight | 25 | Weight for date of birth (0-100) |
| Country Weight | 15 | Weight for country/nationality (0-100) |
***
## API Request Example
```json theme={null}
{
"full_name": "John Doe",
"date_of_birth": "1990-01-01",
"nationality": "USA",
"document_number": "SAMPLE-DOC-12345",
"aml_name_weight": 60,
"aml_dob_weight": 25,
"aml_country_weight": 15,
"aml_match_score_threshold": 93
}
```
***
## Response: Score Breakdown
Each match in the response includes:
* `match_score` — The calculated match score (0-100)
* `risk_score` — The calculated risk score (0-100) - see [Risk Score](/core-technology/aml-screening/aml-risk-score)
* `review_status` — "False Positive" or "Unreviewed" based on match score threshold
* `score_breakdown` — Detailed breakdown of the match score calculation
```json theme={null}
{
"caption": "David Sanchez",
"match_score": 95,
"risk_score": 65.5,
"review_status": "Unreviewed",
"score_breakdown": {
"name_score": 95,
"name_weight": 60,
"name_weight_normalized": 70.59,
"name_contribution": 67.06,
"dob_score": 100,
"dob_weight": 25,
"dob_weight_normalized": 29.41,
"dob_contribution": 29.41,
"country_score": 0,
"country_weight": 15,
"country_weight_normalized": 0,
"country_contribution": 0,
"document_number_match_type": "NEUTRAL",
"document_number_effect": "No document number provided for screening",
"total_score": 95
}
}
```
***
## Complete Flow: From Match Score to Final AML Status
```
┌─────────────────────────────────────────────────────────────────────────────┐
│ AML SCREENING FLOW │
├─────────────────────────────────────────────────────────────────────────────┤
│ │
│ 1. RETRIEVE MATCHES FROM WATCHLISTS │
│ └── All matches with score ≥ 75% are included │
│ │
│ 2. CALCULATE MATCH SCORE FOR EACH MATCH │
│ Match Score = (Name × W1) + (DOB × W2) + (Country × W3) │
│ + Golden Key document number logic │
│ │
│ 3. CLASSIFY MATCHES BY MATCH SCORE (Match Score Threshold = 93) │
│ ├── Match Score < 93 → FALSE POSITIVE (excluded from risk assessment) │
│ └── Match Score ≥ 93 → UNREVIEWED (included in risk assessment) │
│ │
│ 4. CALCULATE RISK SCORE FOR NON-FALSE-POSITIVE MATCHES │
│ Risk Score = (Country × 30%) + (Category × 50%) + (Criminal × 20%) │
│ │
│ 5. DETERMINE FINAL AML STATUS (based on highest risk score) │
│ ├── Highest Risk Score < approve_threshold → APPROVED │
│ ├── Highest Risk Score ≤ review_threshold → IN REVIEW │
│ └── Highest Risk Score > review_threshold → DECLINED │
│ │
└─────────────────────────────────────────────────────────────────────────────┘
```
***
## Calculation Examples
### Example 1: Strong Match → Unreviewed
**Screened Data:**
* Name: "Robert J. Smith"
* DOB: "1985-03-15"
* Country: "US"
**Match Data:**
* Name: "Robert James Smith"
* DOB: "1985"
* Country: "United States"
**Calculation:**
1. Name Score: 90% (fuzzy match)
2. DOB Score: 100% (match only has year, year matches)
3. Country Score: 100% (exact match)
```
Match Score = (90 × 0.60) + (100 × 0.25) + (100 × 0.15)
= 54 + 25 + 15
= 94
```
**Result:** Match Score (94) ≥ threshold (93) → **Unreviewed**
→ Risk score will be calculated and used for final AML status
### Example 2: Weak Match → False Positive
**Screened Data:**
* Name: "John Smith"
* DOB: "1990-05-20"
* Country: "US"
**Match Data:**
* Name: "Johnny Smithson"
* DOB: "1975"
* Country: "Canada"
**Calculation:**
1. Name Score: 72% (weak fuzzy match)
2. DOB Score: -100% (year mismatch penalty)
3. Country Score: -50% (country mismatch penalty)
```
Match Score = (72 × 0.60) + (-100 × 0.25) + (-50 × 0.15)
= 43.2 - 25 - 7.5
= 10.7 → 11
```
**Result:** Match Score (11) \< threshold (93) → **False Positive**
→ This match is excluded from risk assessment
### Example 3: Golden Key Override
**Screened Data:**
* Name: "John D. Smith"
* Document Number: "A12345678"
**Match Data:**
* Name: "Jonathan David Smith"
* Document Number: "A12345678"
**Calculation:**
1. Base Score: \~70 (name fuzzy match)
2. Document Number: **MATCH** (exact match)
**Result:** Score overridden to **100** (Golden Key match) → **Unreviewed**
***
## Managing Review Status
After the initial classification, you can manually update each match's review status:
### In the Console
1. Navigate to the session's AML overview
2. Click on a specific match to view details
3. Use the status dropdown to change the review status:
* **Confirmed Match** — Verify the match is the same person
* **False Positive** — Mark the match as not matching
* **Inconclusive** — Unable to determine
***
## Best Practices
1. **Start with default threshold (93)** — This provides a good balance between catching true matches and filtering false positives.
2. **Lower threshold for high-risk scenarios** — If you need to be more cautious, lower the Match Score Threshold to catch more potential matches.
3. **Use document numbers when available** — They provide the strongest identity confirmation and can override low match scores.
4. **Review normalized weights** — Check the normalized weight fields in the score breakdown to understand how missing data affected the score.
5. **Monitor false positive rates** — If too many legitimate matches are being marked as false positives, lower the threshold.