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.

{
    "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.

{
    "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.