sanctions-watchlist-screener

# Sanctions & Watchlist Screener (OFAC, EU, UK, UN)

**Screens people and company names against the OFAC, EU, UK and UN sanctions lists (from the official sources, re-downloaded at least every 6 hours, with each list's publication date in every row) for $3 per 1,000 names.** You pay $0.003 per name that gets a screening row, and if no list can be downloaded nothing is charged. Example: re-screening 2,000 suppliers costs 2,000 × $0.003 = **$6.00**, plus a $0.007 Actor-start fee per run.

**Fairquery** Apify Actor that screens **people and company names** against the main **public sanctions lists**, downloaded **from the official sources** (re-downloaded whenever the cached copy is older than 6 h, configurable 0–12 h): OFAC SDN and Consolidated (US), EU Consolidated Financial Sanctions, the UK Sanctions List (FCDO / OFSI), and the UN Security Council Consolidated List. Each name gets a `potential_match` / `no_match` status, a 0–100 fuzzy score, and the matching entries with aliases, programs, countries and dates of birth.

> **Not a certified screening service.** This is automated fuzzy matching against public lists. It can return false positives and can miss true matches (transliterations, very short names, lists that fail to download). Review every potential match manually against the official source, and get legal advice before acting on results. It does not replace a regulated KYC/AML provider.

## When to use this Actor (LLM / tool selection)

Use it when an agent or workflow needs to:

- Pre-screen a new customer, supplier, vendor or marketplace seller against sanctions lists (KYB / onboarding)
- Re-screen a counterparty list in bulk (thousands of names per run)
- Check whether a company or person is on OFAC, EU, UK or UN lists and see the program and listing details
- Add a sanctions check step to an export, payments or procurement workflow

## Lists and sources

| `lists` id | List | Source |
| --- | --- | --- |
| `OFAC_SDN` | OFAC Specially Designated Nationals | `sanctionslistservice.ofac.treas.gov` SDN.CSV + ALT.CSV + ADD.CSV |
| `OFAC_CONS` | OFAC Consolidated (non-SDN: SSI, NS-MBS, FSE, …) | CONS_PRIM / CONS_ALT / CONS_ADD.CSV |
| `EU` | EU Consolidated Financial Sanctions List | `webgate.ec.europa.eu/fsd/fsf` CSV 1.1 (falls back to CSV 1.0) |
| `UK` | UK Sanctions List (incl. OFSI asset-freeze targets) | `sanctionslist.fcdo.gov.uk` CSV |
| `UN` | UN Security Council Consolidated List | `scsanctions.un.org` XML |

**List freshness and cache.** Parsed lists are cached in a named key-value store in *your* Apify account (`fairquery-sanctions-list-cache`, about 1.6 MB) and reused only while they are younger than `listCacheMaxAgeHours` (default 6, max 12, measured from the download time). An older copy is never used: the list is downloaded again, and if that download fails the list is reported as unavailable rather than served stale. Set `listCacheMaxAgeHours` to 0 to download fresh on every run. Every result row carries `list_versions` with each list's `published_at` (the date stated by the source: OFAC file time, EU `fileGenerationDate`, UK Report Date, UN `dateGenerated`), `source_last_modified`, `fetched_at`, `from_cache` and `cache_age_secs`. Only your account's storage is used; no screened names are stored. If a source is down, the run continues with the other lists and every row reports it in `lists_unavailable`; per-list entry counts, download times and errors are in `RUN_SUMMARY`.

## Matching

- Names are normalised (diacritics, case, punctuation, `&`, legal suffixes such as LLC/GmbH/JSC, honorifics) and compared **token by token** with Jaro-Winkler, so word order (`PUTIN, Vladimir`), extra middle names, and spelling variants (`Poutine`, `Usama/Osama`, `Gaddafi/Qadhafi`) still match.
- Every **alias** (a.k.a., f.k.a., non-Latin script names) is screened; `matched_on` tells you whether the hit was the primary name or an alias.
- Optional **country** (ISO-2 or name) adds `country_match`; `excludeNonMatchingCountry` drops mismatches.
- Optional **dateOfBirth** drops individuals whose listed birth years differ by more than `dobYearTolerance`; entries without a DOB are kept.

## Input

| Field | Type | Default | Description |
| --- | --- | --- | --- |
| `names` | `string[]` | – (sample names are prefilled in the Console form) | One name per line |
| `queries` | object[] | `[]` | `{name, id?, country?, dateOfBirth?, entityType?}` |
| `lists` | `string[]` | all five | `OFAC_SDN`, `OFAC_CONS`, `EU`, `UK`, `UN` |
| `minScore` | int | `85` | 60–100 |
| `maxMatchesPerName` | int | `10` | Top matches per name |
| `entityType` | `any` \| `individual` \| `entity` | `any` | |
| `country` | string | – | Default country for all names |
| `excludeNonMatchingCountry` | bool | `false` | |
| `dobYearTolerance` | int | `1` | |
| `listDownloadTimeoutSecs` | int | `60` | Per list file |
| `maxNames` | int | `10000` | Safety cap |

```json
{
  "names": ["Banco Nacional de Cuba", "Jane Example Smith"],
  "queries": [{ "name": "Ali Khamenei", "id": "cust-42", "country": "IR", "dateOfBirth": "1939" }]
}
```

## Output

```json
{
  "schema_version": "1.0.0", "type": "screening",
  "query": { "name": "Ali Khamenei", "id": "cust-42", "country": "IR", "date_of_birth": "1939", "entity_type": "any" },
  "status": "potential_match", "best_score": 92.5, "match_count": 1,
  "matches": [{
    "score": 92.5, "matched_name": "KHAMENEI, Ali Husseini", "matched_on": "primary",
    "list": "OFAC_SDN", "list_name": "OFAC Specially Designated Nationals (SDN) List", "entry_id": "…",
    "entity_type": "individual", "primary_name": "KHAMENEI, Ali Husseini", "aliases": ["…"], "programs": ["IRAN-EO13876"],
    "countries": ["Iran"], "dates_of_birth": ["19 Apr 1939"], "listed_on": null,
    "country_match": true, "dob_match": true, "source_url": "https://sanctionssearch.ofac.treas.gov/Details.aspx?id=…"
  }],
  "lists_screened": ["OFAC_SDN", "OFAC_CONS", "EU", "UK", "UN"], "lists_unavailable": [],
  "min_score": 85, "disclaimer": "Not a certified screening service. …"
}
```

Error rows (`type: "error"`, never charged): `INPUT_EMPTY`, `MAX_NAMES_EXCEEDED`, `LISTS_UNAVAILABLE` (no list could be downloaded).

## Pricing

| Event | Price | When |
| --- | --- | --- |
| `name-screened` | $0.003 | Each name that gets a screening row (`potential_match` or `no_match`) |
| `apify-actor-start` | $0.007 | Once per run (memory is capped at 512 MB, so always one event) |

Error rows (`INPUT_EMPTY`, `MAX_NAMES_EXCEEDED`, `LISTS_UNAVAILABLE`) are **never charged**. If no list can be downloaded, nothing is charged.

**Worked example:** a monthly re-screen of 2,000 counterparties in one run: 2,000 × $0.003 = **$6.00**, plus $0.007 (512 MB counts as one start event). Put all names into one run: the per-name price is the same, but every run pays its own $0.007 start fee, so a single-name run costs $0.003 + $0.007 = $0.01.

To cap spend, set a maximum cost per run in the run options; the Actor stops cleanly at the limit. `maxNames` caps how many names one run screens. Prices are from the Store pricing tab (October 2026).

## Memory / runtime

Default and maximum **512 MB**. Each run loads and indexes all five lists (about 33k entries, 100k+ names) before screening: about 1–5 s from a fresh cache, or 10–40 s (up to about 60 s when a government server is slow) when the lists are downloaded again. After that, screening runs at hundreds of names per second. Put all names into one run rather than one run per name.

## MCP / Apify tools

Call from agents via [Apify MCP](https://mcp.apify.com) with Actor `fairquery/sanctions-watchlist-screener`:

```json
{ "actor": "fairquery/sanctions-watchlist-screener", "input": { "names": ["Acme Trading LLC"] } }
```

## Local stdio MCP server

The [`mcp/`](./mcp) folder is a stdio MCP server (TypeScript, `@modelcontextprotocol/sdk`) with two tools, both with annotations and output schemas:

| Tool | What it does | Cost |
| --- | --- | --- |
| `screen_names` | Runs this Actor and returns the rows | Needs `APIFY_TOKEN`, billed per name |
| `list_sources` | Lists covered lists, source URLs, score scale, disclaimer | Free, local, no token |

```bash
cd mcp && npm install && npm run build
node scripts/smoke-test.mjs                          # initialize + tools/list + free tool, no token
APIFY_TOKEN=... node scripts/smoke-test.mjs --call   # real call
```

```json
{ "mcpServers": { "fairquery-sanctions-screener": { "command": "node", "args": ["/path/to/sanctions-watchlist-screener/mcp/dist/index.js"], "env": { "APIFY_TOKEN": "<your Apify token>" } } } }
```

Docker: the root `Dockerfile` builds the MCP server image (`docker build -t fairquery-sanctions-screener-mcp .`); it is also the Dockerfile for Glama. The Actor image is `.actor/Dockerfile`. `glama.json` lists `fairquery` as maintainer.

## Works well after

- [Website Contact & Company Enricher](https://apify.com/fairquery/website-contact-company-enricher) or [Google Maps Scraper](https://apify.com/compass/crawler-google-places): screen the company names they return before you onboard a supplier, partner or marketplace seller.
- Any CRM or ERP export of customers, vendors or payees: map name, country and date of birth into `queries` to cut false positives.

## Troubleshooting

| Symptom | Cause and fix |
| --- | --- |
| Run ends with only an `INPUT_EMPTY` row | No names in `names` or `queries`. The sample names in the Console form are prefill only and are not sent with API calls. |
| `lists_unavailable` is not empty | An official source was down or slow. The other lists were still screened. Re-run later, or raise `listDownloadTimeoutSecs` (default 60 s per file). Per-list errors are in `RUN_SUMMARY`. |
| `LISTS_UNAVAILABLE` error and nothing charged | No list could be downloaded at all (network or source outage). Retry later. |
| Too many potential matches for common names | Add `country` and `dateOfBirth` per query, set `entityType`, raise `minScore` (default 85), or turn on `excl