# 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 `excludeNonMatchingCountry`. |
| A known listed name was not matched | Try a lower `minScore` (60–80) and check the spelling or transliteration. Very short names and unusual transliterations can be missed; see the disclaimer. |
| First minute of the run shows no results | This is expected when the cache is older than the window: the lists are downloaded and indexed first (usually 10–40 s, up to about 60 s). |

## FAQ

**Is this a certified screening service?**

No. It is automated fuzzy matching against public lists. Review every potential match against the official source, and use a regulated KYC/AML provider where the law requires one.

**How fresh are the lists?**

They come from OFAC, the European Commission, the UK FCDO and the UN. A run reuses a copy cached in your account only if it was downloaded less than `listCacheMaxAgeHours` ago (default 6 h, max 12 h); otherwise it downloads them again. Each row's `list_versions` shows the publication date and download time of every list used.

**How long does a run take?**

Usually 10–40 s (up to about 60 s) to load the lists, then hundreds of names per second.

**How much does it cost?**

$0.003 per screened name ($3 per 1,000), plus a $0.007 start fee per run. Error rows are free, and nothing is charged if no list loads.

**How do I limit spend?**

Set a maximum cost per run in the run options and/or lower `maxNames`.

**Can an AI agent call it?**

Yes, through [Apify MCP](https://mcp.apify.com) with Actor `fairquery/sanctions-watchlist-screener`, or through the Fairquery MCP server (`npx -y @fairquery/agent-trust-mcp`, tool `sanctions_screen_names`).

## Fairquery family

Other Fairquery tools on the Apify Store. Each one returns structured rows with machine-readable error codes, and error rows are never charged:

- [Email Validator for Agents (MX, Disposable, Typo)](https://apify.com/fairquery/email-validator-mx-disposable): syntax, MX, disposable, role and typo checks without sending mail; $0.79 per 1,000 emails
- [Website Contact & Company Enricher](https://apify.com/fairquery/website-contact-company-enricher): domain in, public business emails, phones, socials and company details out; $3 per 1,000 domains
- [Website Tech, SEO & llms.txt Check for Agents](https://apify.com/fairquery/website-tech-seo-ai-readiness): tech stack, SEO score, AI-crawler rules and llms.txt per site; $1.50 per 1,000 sites
- [LLM Data Guard: PII & Secret Redactor](https://apify.com/fairquery/llm-data-guard-pii-secrets): redact PII and secrets before text reaches an LLM; $1.50 per 1,000 documents + $0.20 per 1,000 findings
- [Dependency Vulnerability Check for Agents](https://apify.com/fairquery/osv-dependency-vulnerability-check): packages and lockfiles against OSV.dev; $0.50 per 1,000 packages + $1.50 per 1,000 vulnerabilities
- [EDGAR Company Facts & Filings for Agents](https://apify.com/fairquery/edgar-company-facts-filings): SEC filings and XBRL facts by ticker, CIK or name; from $1.50 per 1,000 companies
- **MCP server** [`@fairquery/agent-trust-mcp`](https://www.npmjs.com/package/@fairquery/agent-trust-mcp): one MCP server for Claude Desktop, Cursor and VS Code (`npx -y @fairquery/agent-trust-mcp`). It has 7 free tools that need no token, plus paid tools that call the PII, email, sanctions and OSV Actors with your own Apify token.

All Fairquery Actors: https://apify.com/fairquery

## Kits & templates

Optional guides from Fairquery for wiring this Actor into agents and automations (the Actor works fine without them):

- [AI Agent Data Toolkit Quick-Start](https://fairquery.gumroad.com/l/qayngz) (PDF): MCP setup for Claude Desktop and Cursor, API calls, recipes, cost estimates.
- [n8n + Zapier Workflow Template Pack](https://fairquery.gumroad.com/l/koffbf): 10 importable n8n workflows for the four original Fairquery Actors (SEC EDGAR, website/tech, email, OSV); it does not include workflows for this Actor yet, but the patterns adapt easily.
- [Agent Prompt Pack for Research & Lead Ops](https://fairquery.gumroad.com/l/djdilu): 69 prompts for company research, lead cleaning, SEO and security reviews.
- [Agent Starter Kit: 10 copy-paste MCP + n8n recipes](https://fairquery.gumroad.com/l/idvrck) ($5): 10 copy-paste MCP + n8n recipes, with ready-made Claude/Cursor configs and 3 starter workflows.

## Disclaimer

**Not a certified screening service.** Results come from automated fuzzy matching against public lists downloaded from the official sources (at run time or from a cache no older than the freshness window) and are provided as is, without warranty. They may be incomplete, out of date or wrong. Always confirm potential matches with the official publication of the relevant authority (OFAC, European Commission, UK FCDO/OFSI, UN Security Council) and take legal advice before making compliance decisions. Data comes from public government sources; Fairquery is not affiliated with any of them.

## Links

- Apify Store: https://apify.com/fairquery/sanctions-watchlist-screener
- GitHub: https://github.com/fairquery/sanctions-watchlist-screener
- Contact: fairquery@proton.me
- License: MIT

## Development

Local development, tests and deployment notes are in [DEVELOPMENT.md](./DEVELOPMENT.md). The Apify Store README is [`.actor/README.md`](./.actor/README.md).