# OFAC Sanctions Screener (`robin.geekydev/ofac-sanctions-screener`) Actor

Screen people and organizations against the official U.S. Treasury OFAC SDN and Consolidated Non-SDN sanctions lists. Uses live treasury.gov list files (with optional short-lived cache) — no third-party sanctions API, no fabricated data.

- **URL**: https://apify.com/robin.geekydev/ofac-sanctions-screener.md
- **Developed by:** [Robin p](https://apify.com/robin.geekydev) (community)
- **Categories:** AI, Automation, Developer tools
- **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

from $5.00 / 1,000 results

This Actor is paid per event. You are not charged for the Apify platform usage, but only a fixed price for specific events.

Learn more: https://docs.apify.com/platform/actors/running/actors-in-store#pay-per-event

## What's an Apify Actor?

Actors are web data automations that power AI and operations. They run on the Apify platform to scrape websites, process data, connect APIs, and automate workflows.
In Batch mode, an Actor accepts a well-defined JSON input, performs an action which can take anything from a few seconds to a few hours,
and optionally produces a well-defined JSON output, datasets with results, or files in key-value store.
In Standby mode, an Actor provides a web server which can be used as a website, API, or an MCP server.
Actors are written with capital "A".

## How to integrate an Actor?

If asked about integration, you help developers integrate Actors into their projects.
You adapt to their stack and deliver integrations that are safe, well-documented, and production-ready.
The best way to integrate Actors is as follows.

- **AI agents and MCP clients** — the [Apify MCP server](https://docs.apify.com/integrations/mcp.md) at `https://mcp.apify.com` (remote, streamable HTTP, OAuth on first use).
- **Agentic workflows and local Actor development** — [Agent Skills](https://apify.com/.well-known/agent-skills/index.json) with the [Apify CLI](https://docs.apify.com/cli/docs.md): `npm install -g apify-cli`, then `apify login`.
- **JavaScript/TypeScript projects** — the official [JS/TS client](https://docs.apify.com/api/client/js/docs.md): `npm install apify-client`.
- **Python projects** — the official [Python client](https://docs.apify.com/api/client/python/docs.md): `pip install apify-client`.
- **Any other language** — the [REST API](https://docs.apify.com/api/v2.md).

For usage examples, see the [API](#api) section below.

For more details, see Apify documentation as [Markdown index](https://docs.apify.com/llms.txt) and [Markdown full-text](https://docs.apify.com/llms-full.txt).

# README

## OFAC Sanctions Screener

Screen person and organization names against the **official U.S. Treasury OFAC** sanctions lists.

### Data integrity (important)

This Actor uses **only official U.S. Treasury / OFAC list files**:

| Source | Official URL |
|---|---|
| SDN | https://www.treasury.gov/ofac/downloads/sdn.xml |
| Consolidated Non-SDN | https://www.treasury.gov/ofac/downloads/consolidated/consolidated.xml |

- Publisher: **U.S. Department of the Treasury — OFAC**
- Docs: [OFAC Sanctions List Service](https://ofac.treasury.gov/sanctions-list-service)
- **No Cobalt / third-party sanctions API**
- **No embedded or fabricated sanction records in production**
- If the official download fails (and no valid cache exists), the Actor **fails** (it will not invent matches)
- Each result includes `listProvenance` (publish date, fetch time, URLs, `fromCache`) and `dataFabricated: false`

#### Caching

Official XML is gzip-compressed into the named key-value store **`ofac-list-cache`** (keys `OFAC_XML_SDN`, `OFAC_XML_NONSDN`).

- Default TTL: **12 hours** (`cacheTtlHours`)
- Set `forceRefresh: true` to always re-download from treasury.gov and overwrite the cache
- Cache entries are rejected unless they point at the official Treasury URL, set `dataFabricated: false`, and decompress to valid OFAC XML

Matching scores are computed locally (fuzzy name/alias match). List content itself is unmodified OFAC data.

### Pricing

- **$0.005 per successfully screened name** (`$5.00 / 1,000 results`)
- Failed queries go to the errors dataset and are **not** billed

### Input

```json
{
  "queries": ["AEROCARIBBEAN AIRLINES", "Jane Doe"],
  "searchType": "any",
  "sources": ["SDN", "NONSDN"],
  "minScore": 85,
  "maxMatches": 10,
  "forceRefresh": false,
  "cacheTtlHours": 12
}
```

### Output (per query)

Cobalt-like shape with OFAC-backed fields:

- `name`, `matchCount`, `hasMatch`, `matches[]`
- Each match: `score`, `matchSummary`, `sanction` (uid, type, programs, aliases, addresses, IDs, …)
- `listProvenance` — audit trail of which official files were used

### Disclaimer

This tool helps screen against published OFAC lists. It is **not legal advice**. You remain responsible for your own sanctions-compliance process and determinations.

### Local run

```powershell
cd actors\ofac-sanctions-screener
npm install
node ./src/main.js
```

# Actor input Schema

## `queries` (type: `array`):

One or more person or organization names to screen against official OFAC lists.

## `searchType` (type: `string`):

Limit matches by OFAC sdnType. Use 'any' to search all types.

## `sources` (type: `array`):

Which official OFAC files to download. SDN = Specially Designated Nationals. NONSDN = Consolidated Non-SDN lists.

## `minScore` (type: `integer`):

Only return matches with score >= this value.

## `maxMatches` (type: `integer`):

Maximum number of sanction hits to return for each name.

## `address` (type: `string`):

Optional street address to boost address-field matches.

## `city` (type: `string`):

Optional city to boost address-field matches.

## `stateOrProvince` (type: `string`):

Optional state or province to boost address-field matches.

## `postalCode` (type: `string`):

Optional postal/ZIP code to boost address-field matches.

## `caseId` (type: `string`):

Optional ID echoed back on each result for your workflow correlation.

## `forceRefresh` (type: `boolean`):

If true, always re-download official lists from treasury.gov and overwrite the named KV cache. If false, reuse cached official XML for up to cacheTtlHours.

## `cacheTtlHours` (type: `integer`):

How long to reuse officially downloaded OFAC XML from the named key-value store ofac-list-cache (0–168). Cache always stores real Treasury files only — never fabricated data.

## Actor input object example

```json
{
  "queries": [
    "AEROCARIBBEAN AIRLINES",
    "John Smith"
  ],
  "searchType": "any",
  "sources": [
    "SDN",
    "NONSDN"
  ],
  "minScore": 85,
  "maxMatches": 10,
  "forceRefresh": false,
  "cacheTtlHours": 12
}
```

# Actor output Schema

## `results` (type: `string`):

One dataset item per screened name, including official list metadata and matches.

## `summary` (type: `string`):

Totals plus the OFAC publish dates and download URLs used for this run.

## `errors` (type: `string`):

Queries that could not be screened. These are not billed.

# API

You can run this Actor programmatically using our API. Below are code examples in JavaScript, Python, and CLI, as well as the OpenAPI specification and MCP server setup.

## JavaScript example

```javascript
import { ApifyClient } from 'apify-client';

// Initialize the ApifyClient with your Apify API token
// Replace the '<YOUR_API_TOKEN>' with your token
const client = new ApifyClient({
    token: '<YOUR_API_TOKEN>',
});

// Prepare Actor input
const input = {
    "queries": [
        "AEROCARIBBEAN AIRLINES",
        "John Smith"
    ],
    "searchType": "any",
    "sources": [
        "SDN",
        "NONSDN"
    ],
    "minScore": 85,
    "maxMatches": 10,
    "forceRefresh": false,
    "cacheTtlHours": 12
};

// Run the Actor and wait for it to finish
const run = await client.actor("robin.geekydev/ofac-sanctions-screener").call(input);

// Fetch and print Actor results from the run's dataset (if any)
console.log('Results from dataset');
console.log(`💾 Check your data here: https://console.apify.com/storage/datasets/${run.defaultDatasetId}`);
const { items } = await client.dataset(run.defaultDatasetId).listItems();
items.forEach((item) => {
    console.dir(item);
});

// 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/js/docs

```

## Python example

```python
from apify_client import ApifyClient

# Initialize the ApifyClient with your Apify API token
# Replace '<YOUR_API_TOKEN>' with your token.
client = ApifyClient("<YOUR_API_TOKEN>")

# Prepare the Actor input
run_input = {
    "queries": [
        "AEROCARIBBEAN AIRLINES",
        "John Smith",
    ],
    "searchType": "any",
    "sources": [
        "SDN",
        "NONSDN",
    ],
    "minScore": 85,
    "maxMatches": 10,
    "forceRefresh": False,
    "cacheTtlHours": 12,
}

# Run the Actor and wait for it to finish
run = client.actor("robin.geekydev/ofac-sanctions-screener").call(run_input=run_input)

# Fetch and print Actor results from the run's dataset (if there are any)
print(f"💾 Check your data here: https://console.apify.com/storage/datasets/{run.default_dataset_id}")
for item in client.dataset(run.default_dataset_id).iterate_items():
    print(item)

# 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/python/docs/quick-start

```

## CLI example

```bash
echo '{
  "queries": [
    "AEROCARIBBEAN AIRLINES",
    "John Smith"
  ],
  "searchType": "any",
  "sources": [
    "SDN",
    "NONSDN"
  ],
  "minScore": 85,
  "maxMatches": 10,
  "forceRefresh": false,
  "cacheTtlHours": 12
}' |
apify call robin.geekydev/ofac-sanctions-screener --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "type": "http",
            "url": "https://mcp.apify.com/?tools=fetch-actor-details,robin.geekydev/ofac-sanctions-screener"
        }
    }
}

```

The hosted server signs you in with OAuth on first connect, so no API token belongs in this config. Clients without OAuth support can send an `Authorization: Bearer <APIFY_API_TOKEN>` header instead, using a token from API & Integrations in Apify Console (https://console.apify.com/settings/integrations).

## OpenAPI specification

Download the OpenAPI definition: https://api.apify.com/v2/actors/PxNAXvgvPiDp4x6Ak/builds/PKDXeerIHsKnnCNxC/openapi.json