> ## Documentation Index
> Fetch the complete documentation index at: https://docs.compliapi.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Screen a name

> Fuzzy-screen a person, company, vessel or aircraft name against sanctions-list names and aliases

Screens a name against the primary names and aliases of every party on the sanctions lists with name coverage — the **US OFAC SDN** and **OFAC Consolidated (non-SDN)** lists, the **EU** consolidated financial sanctions list, the **UK Sanctions List**, the **Swiss SECO** list, the **UN Security Council Consolidated List**, **Canada's Consolidated Autonomous Sanctions List**, **Australia's DFAT Consolidated List**, the **French Trésor** register and the **Japan MOF** list — covering individuals, entities, vessels and aircraft. The same person listed by several authorities appears once per list, so a hit on six lists returns six matches. Use it when onboarding a customer or vendor, before paying a counterparty, or anywhere you hold a name rather than an identifier.

Matching is fuzzy and explainable:

* **Order-, case-, accent- and punctuation-insensitive** — `Putin Vladimir`, `PUTIN, Vladimir` and `vladimir putin` are the same name.
* **Typo-tolerant per word** — `Vladimr Putin` still scores 96 against `Vladimir PUTIN`. Words of three letters or fewer (`al`, `bin`, `kim`) must match exactly.
* **Partial names** — a query whose words all appear in a longer listed name (or the reverse) matches at a capped score of at most 90, decaying as the longer name grows. A single short word on its own never matches.
* **Aliases and other scripts** — every alias (a.k.a., f.k.a., n.k.a.) is screened, including the Cyrillic, Arabic and Japanese spellings and transliteration variants the lists publish. Aliases a list itself flags as weak or low quality (OFAC's and DFAT's *weak* aliases, the UN's and the UK's "low quality", SECO's `low`, Trésor's *alias faible*, Japan's 確定に十分でない別名) are not matched, but are returned in `metadata.weak_aliases`.
* **No transliteration** — a Latin-script query does not match a name the list publishes only in Cyrillic or Japanese; most lists publish Latin spellings too.

Each listed party appears at most once, under its best-scoring name.

**name** `string` *required*

Name to screen (2–200 characters).

**type** `string`

Only match listed parties of this type: `individual`, `entity`, `vessel` or `aircraft`.

**birth\_date** `string`

`YYYY`, `YYYY-MM` or `YYYY-MM-DD`. Listed parties whose published birth dates **all** disagree are excluded and counted in `excluded`; parties with no published birth date are kept. Listings with several alternative birth dates match if any one agrees, and `circa` dates allow two years either side.

**country** `string`

ISO 3166 code or English country name. Compared against the party's listed nationalities, citizenships, address countries and vessel flag (in English, French or Japanese, as each list publishes them). It ranks matches and explains them in `reasons`, but **never excludes** a match — listed countries are too incomplete to rule a party out.

**id\_number** `string`

A passport, national ID or registration number you hold for the subject. It is compared, ignoring formatting, with the identity documents each candidate party lists: a party that lists the number **ranks first**, ahead of higher name scores, with the reason in `reasons`. A different number is noted but **never excludes** a match — people hold several documents and renew passports. Many listings carry no document at all ("No listed document to compare").

**threshold** `number`

Minimum name score to report, 50–100 (default 85).

**ref** `string`

Your own reference for the subject — a customer, invoice or wallet id, up to 200 characters. Echoed as `ref` in the response and recorded on the call's audit trail.

**limit** `integer`

Maximum matches to return (1–25, default 10).

**lists** `string`

Comma-separated [list slugs](https://docs.compliapi.com/api/screen/lists.md) to screen against. Defaults to every enabled list with name coverage. `lists_checked` names only the lists that actually hold names at the time of the call; lists without name coverage (the crime and risk lists, FBI Lazarus, Israel NBCTF) are dropped, and a filter naming only such lists is a `400`.

## Response

Same verdicts as the [screening envelope](https://docs.compliapi.com/api/screen.md) — `sanctioned` is true only for a sanctions-list match, `flagged` for any match — plus `threshold`, `excluded`, and scored matches:

| Field | Description |
| - | - |
| `value` | The listed name that matched — the primary name or an alias |
| `score` | Name similarity, 0–100. `match` is `exact` at 100, otherwise `partial` |
| `name` | The party's primary name |
| `name_type` | Which name matched: `primary`, `aka`, `fka` or `nka` |
| `party_type` | `individual`, `entity`, `vessel` or `aircraft` |
| `reasons` | Plain-language explanation of the score and of any `birth_date`/`country` comparison |
| `list_versions` (top level) | The version of each list checked — see [list versions](https://docs.compliapi.com/api/screen.md#list-versions) |
| `metadata` | Published facts, as each list publishes them: `dates_of_birth` (ISO dates, `circa YYYY` or `YYYY to YYYY`; OFAC's own `19 Apr 1947` form), `nationalities`, `citizenships`, `countries` (country names in the list's language — the French register writes `RUSSIE`), `places_of_birth`, `vessel`, `weak_aliases`, programmes, … |

```json Example response theme={null}
{
  "value": "Bank Melli",
  "flagged": true,
  "sanctioned": true,
  "lists_checked": ["ofac", "ofac_consolidated", "fr_tresor", "jp_mof_sanctions", "eu_fsf", "uk_fcdo_sanctions", "ch_seco", "un_sc", "ca_sanctions", "au_dfat"],
  "threshold": 85,
  "excluded": 0,
  "matches": [
    {
      "list": "ofac",
      "list_name": "US OFAC SDN",
      "list_type": "sanctions",
      "match": "partial",
      "value": "BANK MELLI IRAN",
      "score": 90.0,
      "name": "BANK MELLI IRAN",
      "name_type": "primary",
      "party_type": "entity",
      "reasons": ["Name is similar to the listed primary name (score 90)"],
      "source_url": "https://sanctionssearch.ofac.treas.gov/Details.aspx?id=25578",
      "metadata": {
        "sdn_name": "BANK MELLI IRAN",
        "programs": "IFSR, IRAN, SDGT",
        "party_type": "entity",
        "countries": ["Iran", "France", "United Arab Emirates"],
        "weak_aliases": ["BMI"]
      }
    }
  ]
}
```

A name match is a lead for review, not a determination: common names produce partial matches with unrelated parties. Pass `birth_date` and `country` to separate namesakes, and treat the final decision as part of your compliance process. Each call is one request against your quota and is written to your organization's audit trail.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.