# US Denied Party Screening API (`automation-lab/us-denied-party-screening-api`) Actor

🛡️ Batch-screen people and companies against the official US Consolidated Screening List with ranked matches, identifiers, restrictions, and source evidence.

- **URL**: https://apify.com/automation-lab/us-denied-party-screening-api.md
- **Developed by:** [Stas Persiianenko](https://apify.com/automation-lab) (community)
- **Categories:** Business
- **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 0 bookmarks
- **User rating**: 5.00 out of 5 stars

## Pricing

Pay per event

This Actor is paid per event. You are not charged for the Apify platform usage, but only a fixed price for specific events.
Since this Actor supports Apify Store discounts, the price gets lower the higher subscription plan you have.

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

## US Denied Party Screening API

Screen people and companies against the official US Consolidated Screening List (CSL) in one repeatable batch workflow.

Submit names, optional countries, and identifiers. Get one review-ready result per query with a deterministic score, `clear`, `review`, or `match` disposition, ranked candidates, and official source evidence.

The Actor downloads the current public CSL directly from the US International Trade Administration. It covers records consolidated from Treasury, Commerce, and State Department sources, including OFAC and BIS lists.

> Screening output is informational. It requires human review and is not legal advice or a final compliance determination.

### What does this denied party screening API do?

The Actor turns a list of counterparty names into structured screening decisions.

For every query it:

- normalizes Unicode, punctuation, spacing, and common company suffixes;
- compares the query with primary and alternate restricted-party names;
- optionally corroborates the result with country or identifier data;
- ranks candidates with transparent evidence;
- preserves your internal reference for downstream joins;
- links back to the official list and source information;
- emits a clear result even when no candidate reaches the review threshold.

It downloads and indexes the official list once per run, so batching names is faster and more economical than downloading the source separately for every counterparty.

### Who is it for?

#### Export and trade compliance teams

Screen consignees, intermediaries, freight partners, and customers before shipment or license review.

#### Procurement teams

Check new suppliers during onboarding and periodically re-screen an approved vendor master.

#### Fintech and KYB teams

Add US restricted-party evidence to a broader customer or business verification workflow.

#### Logistics and marketplaces

Review counterparties before enabling transactions, payouts, fulfillment, or cross-border access.

#### Developers and data teams

Call one Apify API endpoint rather than maintaining a downloader, parser, fuzzy matcher, and result store.

### Why use this Actor?

- **Official source:** current public CSL data comes from `data.trade.gov`.
- **Broad US coverage:** the consolidated dataset spans 13 source lists when available upstream.
- **Batch-first:** screen up to 500 queries in one run.
- **Explainable:** every candidate includes score components and match origin.
- **Review-ready:** addresses, IDs, programs, restrictions, aliases, and official URLs stay together.
- **Deterministic:** the same source snapshot and input produce the same ranking.
- **Integration-friendly:** dataset output exports to JSON, CSV, Excel, webhooks, and APIs.
- **No login:** the useful official source is public and requires no customer API key.

### Which US lists are covered?

Coverage follows the official ITA Consolidated Screening List export.

Typical source records include:

- Specially Designated Nationals (SDN);
- Sectoral Sanctions Identifications (SSI);
- Denied Persons List (DPL);
- Entity List (EL);
- Unverified List (UVL);
- Military End User (MEU) List;
- ITAR Debarred parties;
- Nonproliferation Sanctions;
- Foreign Sanctions Evaders;
- CAPTA and related Treasury lists.

The exact list set and record count can change upstream. Every output row includes `sourceRecordCount`, while every candidate states its `sourceList`.

### Input

The required `queries` array accepts objects. The smallest valid query contains only a name:

```json
{
  "queries": [
    { "name": "BANK OF KUNLUN CO LTD" },
    { "name": "Acme Bicycle Shop" }
  ]
}
```

For stronger evidence and easier joins, add optional fields:

```json
{
  "queries": [
    {
      "name": "BANK OF KUNLUN CO LTD",
      "country": "CN",
      "identifier": "CKLBCNBJ",
      "reference": "vendor-001"
    }
  ],
  "threshold": 72,
  "matchThreshold": 90,
  "maxMatches": 5
}
```

`country` may be a country name or code that appears in official address records. `identifier` may be an entity number, SWIFT/BIC, passport, tax, or another ID present in the CSL record.

### Match controls

| Field | Default | Purpose |
|---|---:|---|
| `threshold` | 72 | Lowest score retained for review |
| `matchThreshold` | 90 | Score producing an automatic `match` disposition |
| `maxMatches` | 5 | Ranked candidates returned for each query |
| `sourceUrl` | official CSL | Advanced deterministic-test or approved-mirror override |

Lowering `threshold` increases recall and false positives. Raising it reduces the review queue but may miss spelling variations.

`matchThreshold` must be equal to or greater than `threshold`.

### Output data

Each dataset row represents one submitted query.

| Field | Type | Description |
|---|---|---|
| `reference` | string or null | Your input reference |
| `query` | object | Submitted name, country, and identifier |
| `normalizedQuery` | string | Name used by the matcher |
| `disposition` | string | `clear`, `review`, or `match` |
| `bestScore` | number | Highest retained candidate score |
| `matches` | array | Ranked candidate evidence |
| `screenedAt` | ISO datetime | Screening timestamp |
| `sourceDataset` | URL | Official JSON source |
| `sourceRecordCount` | number | Records downloaded for this run |
| `disclaimer` | string | Required review warning |

### Match evidence fields

Each object in `matches` includes:

- `score` and the underlying `evidence.nameScore`;
- `matchedName` and whether it was a primary or alternate name;
- `primaryName` and all `alternateNames`;
- `entityType`;
- structured `addresses`;
- typed `identifiers` and `entityNumber`;
- `programs` and `sourceList`;
- `restrictionRemarks`;
- `sourceInformationUrl` and `sourceListUrl`;
- country and identifier corroboration flags.

This context helps an analyst distinguish a true match from a common-name false positive.

### Example output

```json
{
  "reference": "vendor-001",
  "query": {
    "name": "BANK OF KUNLUN CO LTD",
    "country": "CN",
    "identifier": "CKLBCNBJ"
  },
  "normalizedQuery": "bank of kunlun",
  "disposition": "match",
  "bestScore": 100,
  "matches": [
    {
      "score": 100,
      "matchedName": "BANK OF KUNLUN CO LTD",
      "primaryName": "BANK OF KUNLUN CO LTD",
      "sourceList": "Capta List (CAP) - Treasury Department",
      "evidence": {
        "nameScore": 100,
        "countryMatched": true,
        "identifierMatched": true,
        "matchedOn": "primaryName"
      }
    }
  ]
}
```

The complete record also contains addresses, aliases, programs, restriction text, identifiers, and URLs.

### Understanding dispositions

#### `match`

The best score reaches `matchThreshold`, or a supplied identifier exactly matches an official record.

#### `review`

At least one candidate reaches `threshold` but does not satisfy the automatic match rule.

#### `clear`

No candidate reaches `threshold` in the source snapshot used by the run.

A `clear` result does not certify that a transaction is permitted. Organizations must apply their own policies, list scope, ownership rules, geography checks, and legal review.

### How much does it cost to screen denied parties?

The Actor uses pay-per-event pricing.

- Run start: **$0.005**.
- Each screened query at the BRONZE tier: **$0.000072151**.
- Higher Apify plans receive lower per-query tier prices.

A 100-name BRONZE run is approximately $0.0122 before platform-specific credits or plan terms.

You are charged for completed query results, not for every candidate inspected internally.

### Step-by-step workflow

1. Open the Actor input page.
2. Paste names into `queries` as strings or objects.
3. Add country, identifier, and reference where available.
4. Keep the default thresholds for an initial run.
5. Start the Actor.
6. Export the dataset or consume it through the API.
7. Route `match` and `review` outcomes to a trained analyst.
8. Save the source timestamp and evidence with your case record.
9. Re-screen counterparties according to your compliance policy.

### Tips for better screening

- Supply the full legal name rather than a trading nickname alone.
- Include country when the name is common.
- Include authoritative identifiers whenever available.
- Keep `maxMatches` high enough for analyst review on short names.
- Test thresholds against known positive and negative cases before production use.
- Preserve `reference` so results join reliably to your system.
- Treat alternate-name matches as meaningful evidence, not automatic proof.
- Re-screen because official lists change.

### Integrations

#### Vendor onboarding

Trigger a run from a procurement workflow, join on `reference`, and pause approval when disposition is `review` or `match`.

#### CRM or KYB pipeline

Send newly created organizations in daily batches and store the source URLs with the customer record.

#### Webhooks

Use an Apify run-finished webhook to send dataset results to an internal compliance queue.

#### Google Sheets and Excel

Export dataset rows for an analyst-operated review queue. Nested matches remain available in JSON.

#### Zapier, Make, and n8n

Start a run when a counterparty is created, then branch automation on `disposition`.

### Apify API with cURL

```bash
curl -X POST \
  "https://api.apify.com/v2/acts/automation-lab~us-denied-party-screening-api/runs?token=$APIFY_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"queries":[{"name":"BANK OF KUNLUN CO LTD","country":"CN"}]}'
```

Poll the returned run or use a webhook, then read its default dataset.

### Apify API with JavaScript

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

const client = new ApifyClient({ token: process.env.APIFY_TOKEN });
const run = await client.actor('automation-lab/us-denied-party-screening-api').call({
  queries: [
    { name: 'BANK OF KUNLUN CO LTD', country: 'CN', reference: 'vendor-001' },
  ],
});
const { items } = await client.dataset(run.defaultDatasetId).listItems();
console.log(items);
```

### Apify API with Python

```python
import os
from apify_client import ApifyClient

client = ApifyClient(os.environ['APIFY_TOKEN'])
run = client.actor('automation-lab/us-denied-party-screening-api').call(run_input={
    'queries': [
        {'name': 'BANK OF KUNLUN CO LTD', 'country': 'CN', 'reference': 'vendor-001'}
    ]
})
items = client.dataset(run['defaultDatasetId']).list_items().items
print(items)
```

### Use with Apify MCP

#### Claude Code setup

```bash
claude mcp add --transport http apify "https://mcp.apify.com?tools=automation-lab/us-denied-party-screening-api"
```

#### Claude Desktop, Cursor, and VS Code setup

Add this MCP JSON block to Claude Desktop, Cursor, or VS Code and provide your Apify token through the client’s supported authentication configuration:

```json
{
  "mcpServers": {
    "apify": {
      "url": "https://mcp.apify.com?tools=automation-lab/us-denied-party-screening-api"
    }
  }
}
```

Example prompts:

- “Use the US Denied Party Screening API tool to screen these supplier names and summarize every result needing review.”
- “Use MCP to check this company name and SWIFT code against the US consolidated list.”
- “Run the screening Actor and create a CSV-ready review queue from these counterparties.”

### Data freshness and source behavior

The Actor fetches the official JSON at run time rather than shipping a stale embedded copy.

The ITA import cadence and individual source-list update times vary. A run records its own `screenedAt` timestamp and source record count, but upstream publication time remains controlled by US agencies.

If the official endpoint is unavailable or returns a malformed partial payload, the Actor fails instead of returning misleading clear results.

### Limitations

- Fuzzy matching cannot determine identity by itself.
- Transliteration and aliases depend on the official records available upstream.
- Country corroboration uses listed addresses and may be incomplete.
- Ownership and “50 percent rule” analysis is outside this Actor’s scope.
- Non-US sanctions, PEP, and adverse-media screening are not comprehensively covered.
- A name absent today may appear after an upstream update.
- Very short or generic names produce broader review queues.
- The maximum batch size is 500 queries per run.

### Compliance and legal notice

This Actor is a research and workflow tool, not a law firm, compliance officer, or government determination service.

Users are responsible for deciding which lists, thresholds, ownership rules, jurisdictions, and escalation procedures apply to their transactions.

Do not use a score as the sole basis for an adverse decision about a person. Verify identity with appropriate evidence and follow applicable law, contracts, and internal policy.

The source data remains attributable to the relevant US government agencies through the included URLs.

### Troubleshooting

#### Why did a known name return `review` rather than `match`?

The spelling may differ, the name may match only an alias, or your `matchThreshold` may be conservative. Inspect `evidence`, country, IDs, and official remarks before changing thresholds.

#### Why did a common company name return many candidates?

Common tokens create ambiguity. Add country or identifier evidence, raise `threshold`, and retain enough candidates for trained review.

#### Why did the run fail before producing results?

The official dataset may be unavailable or malformed, or an input constraint may be invalid. Inspect the run log. The Actor deliberately fails closed rather than issuing unsupported clear outcomes.

#### Why is country corroboration false?

Use a country code or name consistent with official address data. Some restricted-party records have no address, so false means “not corroborated by listed addresses,” not “different identity.”

### FAQ

#### Does this replace legal or compliance review?

No. Every result includes a disclaimer and should feed a documented human-review process.

#### Is `clear` a guarantee?

No. It means no candidate reached your threshold in the downloaded CSL snapshot.

#### Can I screen hundreds of names?

Yes. One run accepts up to 500 queries and downloads the source only once.

#### Are alternate names included?

Yes. Primary and alternate names are indexed, and `matchedOn` identifies which produced the retained score.

#### Can I use my own internal ID?

Yes. Put it in `reference`; the Actor copies it to the corresponding output row.

#### Does the Actor need a proxy or login?

No. It uses the official anonymous JSON export.

### Related Automation Lab actors

For raw record exports and broader entity datasets, consider:

- [OFAC Sanctions List Export Scraper](https://apify.com/automation-lab/ofac-sanctions-list-export-scraper)
- [OpenSanctions Entities Scraper](https://apify.com/automation-lab/opensanctions-entities-scraper)

Choose this Actor when your primary workflow starts with names to screen and needs one scored outcome per query. Choose an export Actor when you primarily need the full underlying list for your own matching system.

### Support

When reporting a problem, include a reproducible input with non-sensitive sample names, the run ID, expected disposition, actual disposition, and why the official evidence suggests a different result.

Do not send private identity documents or confidential customer data in a public support message.

# Actor input Schema

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

Names as strings or objects with name plus optional country, identifier, and your reference. Maximum 500 queries.

## `threshold` (type: `integer`):

Minimum fuzzy score (0–100) retained for human review. Lower values increase false positives.

## `matchThreshold` (type: `integer`):

A best score at or above this value produces disposition=match.

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

Number of ranked candidate records included in each screening result.

## `sourceUrl` (type: `string`):

Advanced/testing override. Keep the default empty to use the current official ITA CSL JSON export.

## Actor input object example

```json
{
  "queries": [
    {
      "name": "BANK OF KUNLUN CO LTD",
      "country": "CN",
      "identifier": "CKLBCNBJ",
      "reference": "vendor-001"
    },
    {
      "name": "Acme Bicycle Shop",
      "country": "US",
      "reference": "vendor-002"
    }
  ],
  "threshold": 72,
  "matchThreshold": 90,
  "maxMatches": 5
}
```

# Actor output Schema

## `screeningResults` (type: `string`):

Default dataset containing one explainable denied-party screening result per submitted query.

# 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": [
        {
            "name": "BANK OF KUNLUN CO LTD",
            "country": "CN",
            "identifier": "CKLBCNBJ",
            "reference": "vendor-001"
        },
        {
            "name": "Acme Bicycle Shop",
            "country": "US",
            "reference": "vendor-002"
        }
    ],
    "threshold": 72,
    "matchThreshold": 90,
    "maxMatches": 5
};

// Run the Actor and wait for it to finish
const run = await client.actor("automation-lab/us-denied-party-screening-api").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": [
        {
            "name": "BANK OF KUNLUN CO LTD",
            "country": "CN",
            "identifier": "CKLBCNBJ",
            "reference": "vendor-001",
        },
        {
            "name": "Acme Bicycle Shop",
            "country": "US",
            "reference": "vendor-002",
        },
    ],
    "threshold": 72,
    "matchThreshold": 90,
    "maxMatches": 5,
}

# Run the Actor and wait for it to finish
run = client.actor("automation-lab/us-denied-party-screening-api").call(run_input=run_input)

# Fetch and print Actor results from the run's dataset (if there are any)
print("💾 Check your data here: https://console.apify.com/storage/datasets/" + run["defaultDatasetId"])
for item in client.dataset(run["defaultDatasetId"]).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": [
    {
      "name": "BANK OF KUNLUN CO LTD",
      "country": "CN",
      "identifier": "CKLBCNBJ",
      "reference": "vendor-001"
    },
    {
      "name": "Acme Bicycle Shop",
      "country": "US",
      "reference": "vendor-002"
    }
  ],
  "threshold": 72,
  "matchThreshold": 90,
  "maxMatches": 5
}' |
apify call automation-lab/us-denied-party-screening-api --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "command": "npx",
            "args": [
                "mcp-remote",
                "https://mcp.apify.com/?tools=automation-lab/us-denied-party-screening-api",
                "--header",
                "Authorization: Bearer <YOUR_API_TOKEN>"
            ]
        }
    }
}

```

## OpenAPI specification

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