# Sanctions PEP Screening API - AML Watchlist, Adverse Media (`nabeelbaghoor/sanctions-pep-screening-api`) Actor

Sanctions, PEP and adverse media screening with the ComplyAdvantage API: screen people, companies, vessels and aircraft against global sanctions lists, watchlists, PEP classes and adverse media, then read past searches, hits and monitoring changes. Bring your own key.

- **URL**: https://apify.com/nabeelbaghoor/sanctions-pep-screening-api.md
- **Developed by:** [Nabeel Hassan](https://apify.com/nabeelbaghoor) (community)
- **Categories:** Business, Developer tools, Automation
- **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

from $20.00 / 1,000 screening hit returneds

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/actors/running/actors-in-store.md#pay-per-event

## What's an Apify Actor?

An Actor is a serverless cloud program that runs on the Apify platform. It has two run modes.
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.

Apify vocabulary and the platform model are defined once, in the agent quickstart at https://apify.com/agents.md.

## 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.

Do not guess an integration path. Every one of them is in the agent quickstart at https://apify.com/agents.md: the Apify MCP server, Agent Skills with the Apify CLI, the JavaScript and Python clients, the REST API, and the account-free path for an agent with no human to sign in. It also carries the rule on stating cost before the first paid run.

For examples already wired to this Actor's own input schema, see the [API](#api) section below.

Each client library has reference documentation the quickstart does not restate: [JavaScript/TypeScript](https://docs.apify.com/api/client/js/docs.md) (`npm install apify-client`) and [Python](https://docs.apify.com/api/client/python/docs.md) (`pip install apify-client`).

# README

## Sanctions PEP Screening API - AML Watchlist, Adverse Media

Screen people, companies, vessels and aircraft against global sanctions lists, watchlists, politically exposed persons (PEPs) and adverse media through the ComplyAdvantage API with your own key, and get every hit as a clean dataset row.

Works with the ComplyAdvantage API (docs.complyadvantage.com/api-docs) on the EU, US or APAC host: POST /searches to screen a name, GET /searches for search history, GET /searches/{id}/details and /searches/{ref}/entities/{provider} for hits, and GET /searches/{id}/monitors and /monitor/differences for ongoing monitoring. Each hit becomes one row with the matched entity, AML types (sanction, warning, fitness and probity, PEP class, adverse media category), list sources, countries, birth dates, aliases, associates, adverse media count, match types and score, plus the full ComplyAdvantage record. Download as JSON, CSV or Excel, schedule it, or feed it into a KYC, onboarding or case management workflow or an AI agent. Bring your own API key.

BYOK, not live-tested: every route, body field, filter and response field comes from ComplyAdvantage's published API reference, and every route prefix was confirmed to exist on api.complyadvantage.com, but the actor has not been run against a live ComplyAdvantage account.

### What it does

- **Screen names**: one new ComplyAdvantage search per name, against sanctions, warnings, fitness and probity, PEP classes 1 to 4 and adverse media (classic or FATF aligned v2 taxonomy). Filter by entity type, birth year, country codes, fuzziness, exact match, deceased people, or a saved search profile. One row per hit with the search ID and ref, so you can come back to it.
- **Search history**: page through past searches in your account by match status, risk level, search term, client reference, created date range, assignee, searcher, monitoring state or tags, sorted as you choose.
- **Search details**: the full hits of any past search by ID or ref.
- **Search entities**: page through every hit of a search beyond the first 100, from ComplyAdvantage data or your own internal lists.
- **Monitor status**: whether each search is under ongoing monitoring, and when the monitor last ran.
- **Monitor differences**: entities added, removed or updated on a monitored search on a given day, with the list types and sources that changed.
- **Read only after screening**: no route that changes match status, risk level, assignee, tags, comments or monitoring is called.
- **Pay only for results**: a screening with no hits, or a lookup that returns nothing, gives one free row that says why.

### Important: screening creates searches in your account

Screen mode calls POST /searches once per name. ComplyAdvantage creates each search in your account (it shows in the web app's case management, assigned to the key's user) and counts it toward the search volume in your contract, which ComplyAdvantage bills under your own agreement. Screening the same list twice runs twice the searches. The run stops starting new searches once `maxResults` rows are reached, so no search is created that the run cannot return. To read results again, use Search details with the search ref instead of screening again. Every other mode only reads.

### How to get an API key

ComplyAdvantage API access is part of a ComplyAdvantage contract (pricing through their sales team; sandbox accounts exist for integration testing). In the ComplyAdvantage web app, a user with API access creates an API key (or the account admin issues one). Paste it into the API key field, or set the DATA_API_KEY secret, and pick the region your account lives on: EU (api.complyadvantage.com), US (api.us.complyadvantage.com) or APAC (api.ap.complyadvantage.com). The key is sent only to that host in the Authorization header as `Token <key>` and is never logged. A missing or rejected key ends the run cleanly with a status message.

### Input

| Field | Modes | Description |
| --- | --- | --- |
| `mode` | all | `screen`, `searchHistory`, `searchDetails`, `searchEntities`, `monitorStatus` or `monitorDifferences` |
| `searchTerms` | screen | Names to screen, one per line (up to 1,000 a run, 255 characters each) |
| `entityType` | screen | person, company, organisation, vessel or aircraft |
| `types` | screen | sanction, warning, fitness-probity, pep, pep-class-1 to 4, adverse-media types (classic or v2) |
| `searchProfile` | screen | Search profile ID (UUID) from the web app; not with `types` |
| `birthYear` | screen | Year of birth |
| `countryCodes` | screen | ISO alpha-2 country codes |
| `fuzziness` | screen | 0 to 1 |
| `exactMatch` | screen | Turn off name variation matching |
| `removeDeceased` | screen | Leave deceased people out |
| `clientRef` | screen, search history | Your customer reference (screen: one name per run) |
| `hitsPerSearch` | screen | Hits per search, 1 to 100 |
| `shareUrl` | screen, search details | Ask for a public share link |
| `searchIds` | details, entities, monitor modes | Numeric search IDs or refs |
| `entityProvider` | search entities | comply or internal |
| `differencesDate` | monitor differences | Day to report, YYYY-MM-DD (default today) |
| `matchStatus`, `riskLevel` | search history | Status and risk level filters |
| `searchTermFilter` | search history | Term contains, 3 characters minimum |
| `createdFrom`, `createdTo` | search history | Created date range |
| `assigneeId`, `searcherId` | search history | ComplyAdvantage user IDs |
| `monitored` | search history | un-suspended, suspended or false |
| `tags`, `tagsLogicalOperator` | search history | name:value tags, matched with OR or AND |
| `sortBy`, `sortDir` | search history | id, created_at, updated_at, assignee_id or searcher_id; ASC or DESC |
| `region` | all | eu, us or ap |
| `maxResults` | all | Row ceiling for the run (default 100) |
| `requestsPerMinute` | all | Pacing, default 60 |
| `apiKey` | all | Your ComplyAdvantage API key (or the DATA_API_KEY secret) |

An input set for a mode that does not take it is left off with a warning, never sent.

Example: screen two companies for sanctions and warnings only.

```json
{
    "mode": "screen",
    "searchTerms": ["Acme Trading Ltd", "Northwind Shipping LLC"],
    "entityType": "company",
    "types": ["sanction", "warning"],
    "fuzziness": 0.6,
    "maxResults": 50
}
```

### Example output

An illustrative screening hit, shaped like the documented POST /searches response (values are an example). The full hit is kept under `record`.

```json
{
    "mode": "screen",
    "recordType": "hit",
    "found": true,
    "input": "Robert Mugabe",
    "searchId": 46,
    "searchRef": "1495711341-Tu51KL9s",
    "searchTerm": "Robert Mugabe",
    "searchMatchStatus": "potential_match",
    "searchRiskLevel": "unknown",
    "totalHits": 1,
    "entityId": "RU4326M8GFUAHMF",
    "entityName": "Mugabe Robert Gabriel",
    "entityType": "person",
    "amlTypes": "sanction",
    "sources": "swiss-seco-list",
    "countries": "Zimbabwe",
    "birthDates": "1924",
    "akaNames": null,
    "associates": "Grace Mugabe (Spouse)",
    "mediaCount": 1,
    "latestMediaTitle": "Example news headline",
    "latestMediaUrl": "https://news.example.com/article",
    "matchTypes": "name_exact; year_of_birth",
    "score": 3.511,
    "hitMatchStatus": null,
    "isWhitelisted": false,
    "entityUpdatedAt": "2015-06-16T01:11:14Z",
    "createdAt": "2015-06-18 16:52:42",
    "updatedAt": "2015-06-18 16:52:42",
    "isMonitored": null,
    "changeAction": null,
    "shareUrl": null,
    "note": null,
    "record": { "doc": { "id": "RU4326M8GFUAHMF", "types": ["sanction"] }, "match_types": ["name_exact", "year_of_birth"], "score": 3.511 }
}
```

### FAQ

#### What is the ComplyAdvantage API?

ComplyAdvantage (IVXS UK Limited) is an AML and financial crime risk data provider. Its REST API screens names against its global database of sanctions lists (OFAC, UN, EU, HM Treasury and many more), watchlists and enforcement lists, politically exposed persons in four classes, and adverse media, and keeps every screening as a search you can review, assign and monitor.

#### Do I need my own ComplyAdvantage API key?

Yes. This is a bring-your-own-key actor: it calls ComplyAdvantage with your key, under your contract and its terms. A missing or rejected key ends the run cleanly with a status message, and nothing is charged.

#### Does screening cost me ComplyAdvantage searches?

Yes. Each name in Screen mode is one POST /searches, which creates a search in your ComplyAdvantage account and counts toward your contracted search volume. Reading past searches, hits and monitoring changes does not create searches.

#### How do I reduce false positives?

Set the entity type, add a birth year for people, add country codes, lower the fuzziness or turn on exact match, and narrow the screening types. Setting a client reference makes ComplyAdvantage stop reporting hits you already reviewed for that customer.

#### How do I get more than 100 hits for one name?

A search returns at most 100 hits. Run Search entities with the search ref from the Screen row to page through all of its hits.

#### Can I screen against PEPs only, or adverse media only?

Yes. Choose only the PEP classes, or only adverse media types, under Screening types. Use the classic adverse media types or the FATF aligned v2 types, matching the taxonomy your account uses. Or pick a search profile set up in the web app instead.

#### Does this actor turn monitoring on or off?

No. It reads monitoring status and daily monitoring differences, but it never switches monitoring, acknowledges changes or edits a search.

#### What do I pay?

Pay per result: 0.02 USD per screening hit and 0.01 USD per past search, monitor status or monitoring change. Screenings with no hits and lookups that return nothing are never charged. Your ComplyAdvantage contract is billed separately by ComplyAdvantage.

### Pricing

| Event | Price | Charged for |
| --- | --- | --- |
| `screening-hit` | 0.02 USD | Each sanctions, watchlist, PEP or adverse media hit, from Screen, Search details or Search entities |
| `search-record` | 0.01 USD | Each past search, monitor status or monitoring change |

### Keyword map

sanctions screening API, PEP screening API, AML screening, adverse media screening, watchlist screening, OFAC screening, KYC screening, KYB screening, politically exposed persons check, sanctions list check, negative news screening, vessel sanctions screening, ongoing monitoring, AML compliance automation, ComplyAdvantage API, financial crime risk data for AI agents.

### Terms and data use

ComplyAdvantage data is licensed under your agreement with ComplyAdvantage (IVXS UK Limited Terms of Service and your Order Form). Those terms make ComplyAdvantage data available only for your own use as part of the services (clause 7.1), forbid extracting the data in bulk (10.1.6), releasing it to third parties or anyone who is not your employee without written consent (10.1.7, 10.1.9), and selling, renting or sub-licensing it (11.2). They let you keep the details and results of your screenings after the agreement ends for legal and compliance purposes (12.6). The terms also carry an FCRA notice: the data must not be used as a consumer report, for example for credit or employment decisions. Run this actor with your own key, screen your own customers and counterparties, keep the results for your own compliance records, and do not share or resell them. This actor is not affiliated with or endorsed by ComplyAdvantage.

# Actor input Schema

## `mode` (type: `string`):

Screen runs a new ComplyAdvantage search for each name (sanctions, watchlists, PEPs and adverse media) and returns one row per hit; each search is created in your account and counts toward your contracted search volume. The other modes only read: past searches, the hits of given searches, their paged entities, monitoring status and monitoring changes.

## `searchTerms` (type: `array`):

Screen only. One person, company, vessel or aircraft name per line (at most 255 characters each, up to 1,000 per run). Each name is one new ComplyAdvantage search.

## `entityType` (type: `string`):

Screen only. Tunes name matching to a person, company, organisation, vessel or aircraft (titles, legal suffixes, nicknames, initials). ComplyAdvantage notes it is not a hard filter between entity types.

## `types` (type: `array`):

Screen only. Which lists to check. Leave empty to use your account default. Use the classic adverse media types or the FATF aligned v2 types, whichever taxonomy your account uses. Cannot be combined with a search profile.

## `searchProfile` (type: `string`):

Screen only. The ID (a UUID) of a search profile set up in the ComplyAdvantage web app, which fixes the lists and settings to use. Leave screening types empty when you set this.

## `birthYear` (type: `integer`):

Screen only. Year of birth, when known, to cut false positives on people.

## `countryCodes` (type: `array`):

Screen only. ISO 3166-1 alpha-2 codes such as GB, US or RU. Narrows PEP and country tagged results; sanctioned entities and adverse media only results still appear whatever the country.

## `fuzziness` (type: `number`):

Screen only. How loosely names may match, from 0 (no one letter typos) to 1 (loosest). ComplyAdvantage examples use 0.6. Leave empty for your account default.

## `exactMatch` (type: `boolean`):

Screen only. Turns off all name variation matching (honorifics, initials, nicknames, glued names, extra words). Overrides fuzziness.

## `removeDeceased` (type: `boolean`):

Screen only. Leaves deceased people out of the results.

## `clientRef` (type: `string`):

Screen: your own reference for the customer being screened (one name per run when set). ComplyAdvantage tracks results per reference and stops reporting hits you have already reviewed for that customer. Search history: show searches with this reference.

## `hitsPerSearch` (type: `integer`):

Screen only. The most hits each search pulls, 1 to 100 (the API maximum per search).

## `shareUrl` (type: `boolean`):

Screen and Search details. Asks ComplyAdvantage for a shareable link to the search result. The link opens the result publicly, so leave this off unless you need it.

## `searchIds` (type: `array`):

Search details, Search entities, Monitor status and Monitor differences. Numeric search IDs or search refs such as 1594889804-eVSo1JXO (Search history and Screen rows give both).

## `entityProvider` (type: `string`):

Search entities only. comply reads hits from ComplyAdvantage data; internal reads hits from your own uploaded internal lists (blacklists).

## `differencesDate` (type: `string`):

Monitor differences only. The day to report changes for, YYYY-MM-DD. Leave empty for today.

## `matchStatus` (type: `array`):

Search history only. Keep searches with any of these match statuses.

## `riskLevel` (type: `array`):

Search history only. Keep searches with any of these risk levels.

## `searchTermFilter` (type: `string`):

Search history only. Keep searches whose term matches this text (3 characters minimum).

## `createdFrom` (type: `string`):

Search history only. Searches made on or after this date, YYYY-MM-DD.

## `createdTo` (type: `string`):

Search history only. Searches made on or before this date, YYYY-MM-DD.

## `assigneeId` (type: `integer`):

Search history only. Searches assigned to this ComplyAdvantage user ID.

## `searcherId` (type: `integer`):

Search history only. Searches run by this ComplyAdvantage user ID.

## `monitored` (type: `string`):

Search history only. Actively monitored, suspended, or not monitored searches.

## `tags` (type: `array`):

Search history only. Tags as name:value, such as internal_ref:1234.

## `tagsLogicalOperator` (type: `string`):

Search history only, with two or more tags. OR keeps searches with any tag, AND only those with all of them.

## `sortBy` (type: `string`):

Search history only. Leave empty for the stored order.

## `sortDir` (type: `string`):

Search history only, with a sort field.

## `region` (type: `string`):

The ComplyAdvantage region your account lives on. A key works only on its own region.

## `maxResults` (type: `integer`):

The most rows this run returns. In Screen mode the run stops starting new searches once it is reached, so no search is wasted.

## `requestsPerMinute` (type: `integer`):

Pacing. ComplyAdvantage allows 600 calls a minute on a standard contract and 300 on a sandbox. A rate limit answer is waited out and retried.

## `apiKey` (type: `string`):

Your own ComplyAdvantage API key, created in the ComplyAdvantage web app. Stored as a secret, sent only to the ComplyAdvantage API host of your region in the Authorization header, and never logged. You can instead set the DATA_API_KEY environment secret.

## Actor input object example

```json
{
  "mode": "screen",
  "searchTerms": [
    "Robert Mugabe"
  ],
  "types": [
    "sanction",
    "warning",
    "pep",
    "adverse-media"
  ],
  "exactMatch": false,
  "removeDeceased": false,
  "hitsPerSearch": 100,
  "shareUrl": false,
  "entityProvider": "comply",
  "tagsLogicalOperator": "OR",
  "sortDir": "DESC",
  "region": "eu",
  "maxResults": 20,
  "requestsPerMinute": 60
}
```

# Actor output Schema

## `records` (type: `string`):

One row per hit, search, monitor status or monitoring change for the chosen mode.

# 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 = {
    "searchTerms": [
        "Robert Mugabe"
    ],
    "types": [
        "sanction",
        "warning",
        "pep",
        "adverse-media"
    ],
    "maxResults": 20
};

// Run the Actor and wait for it to finish
const run = await client.actor("nabeelbaghoor/sanctions-pep-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 = {
    "searchTerms": ["Robert Mugabe"],
    "types": [
        "sanction",
        "warning",
        "pep",
        "adverse-media",
    ],
    "maxResults": 20,
}

# Run the Actor and wait for it to finish
run = client.actor("nabeelbaghoor/sanctions-pep-screening-api").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 '{
  "searchTerms": [
    "Robert Mugabe"
  ],
  "types": [
    "sanction",
    "warning",
    "pep",
    "adverse-media"
  ],
  "maxResults": 20
}' |
apify call nabeelbaghoor/sanctions-pep-screening-api --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "type": "http",
            "url": "https://mcp.apify.com/?tools=fetch-actor-details,nabeelbaghoor/sanctions-pep-screening-api"
        }
    }
}
```

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/SWyA4VSb1R7K3nWLe/builds/fdnATEzuzq7jixUjr/openapi.json