Skip to content
Console(opens in a new tab)

Watchlist screening

What watchlist screening covers, the lists it screens, and the watchlist task and hit objects it returns.

Watchlist screening is an add-on task that you request with attrs=watchlist. It works on a business request or on one person alone. The outcome comes back in two places: the watchlist task in risk_summary.tasks, which How checks work lists beside the other checks, and a top-level watchlists array with one object per watchlist hit.

This page defines what screening covers and what it returns. To request it, see Screen a business and Screen a person, which the examples below come from.

A person-only screen of Jane Smith, trimmed to the watchlist task and the watchlists array. Each object in watchlists is one hit; the fields are under Watchlist hits.

200 OK
{
"risk_summary": {
"tasks": [
{
"task_name": "watchlist",
"status": "failure",
"result": "watchlist_hits",
"reason": "1 hit(s) were identified on the consolidated sanctions list (including OFAC)"
}
]
},
"response_id": "2a1b3c4d-5e6f-7890-abcd-ef1234567890",
"watchlists": [
{
"id": "ofac/sdn/58210",
"match_confidence": 0.87,
"watchlist_entity": {
"watchlist_name": "SDN",
"entity_type": "person",
"full_name": "JANE SMITHE",
"organization_name": null,
"dob": null,
"full_address": null
},
"matched_fields": {
"person_name": "JANE SMITHE"
}
}
]
}

On a business request, Enigma screens:

  • Each business name you send.
  • The registered entities Enigma finds for your input, including ones it considered but did not return in data.
  • The registered persons on those registered entities’ registrations: the people and organizations named on them, such as officers and agents.

Hits from all of these come back together in one watchlists array. A hit does not say which name or record produced it, and it can come from a registered entity that is not in data. Do not assume that a hit is about the registered entity in the response. A hit can be driven by an address or a date of birth as well as by a name; matched_fields says which.

Screening has coverage limits. Screening may not cover every registered entity found for your input, every officer and agent on a registration, or every legal entity linked to a brand, and each screened record returns a limited number of hits. A watchlist_no_hits result covers what was screened, not every possible listing.

The submitted person (person, or the one item in persons) is used for matching and for the person_verification task. Screening of the submitted person on a business request is not guaranteed, so do not rely on it. To screen a specific individual, such as a beneficial owner or an applicant, send a person-only screen.

Each hit’s watchlist_entity.watchlist_name names the list it came from.

watchlist_name List Category
SDN The U.S. Treasury Office of Foreign Assets Control (OFAC) Specially Designated Nationals list. Sanctions
non-SDN The OFAC consolidated non-SDN sanctions lists. Sanctions
UN The United Nations Security Council Consolidated List. Sanctions
World Bank The World Bank Listing of Ineligible Firms and Individuals. Debarment
PEP Enigma’s list of politically exposed persons, compiled from public sources. See PEP coverage. Politically exposed

These values are not a closed set. A hit can carry a watchlist_name not listed here, or null. Handle both in code.

OFAC, the UN and the World Bank publish their own lists. No authoritative registry of politically exposed persons exists, so Enigma compiles its list and focuses on senior public officials in major jurisdictions. Coverage varies by jurisdiction and role. A person outside the groups below may not be listed, so a clean screen does not show that someone is not a PEP.

The list covers these roles:

Role group Covers
Executive Heads of state and government, cabinet members and national government ministers.
Legislative Members of national legislatures and parliaments.
Judicial High-court and supreme-court justices.
Financial Central bank leaders and financial regulators.
Regional government Governors, premiers and regional leaders.
State-owned enterprises Senior officials of state-owned entities, in selected jurisdictions.

It covers these jurisdictions and institutions:

Jurisdiction Institutions covered
United States Executive Cabinet, Congress, state governors, federal regulatory agency heads and the Supreme Court.
Canada Federal Cabinet, Parliament, provincial and territorial premiers, regulatory bodies and the Supreme Court.
European Union European Commissioners, Members of the European Parliament, the EU judiciary and European Central Bank leadership.
Russia The executive branch, the Federal Assembly, the Central Bank and senior officials of state-owned enterprises.
Central, South and East Asia National government officials across Central Asia, South Asia (including India and Pakistan) and East Asia, and central bank leadership across the region.
Middle East Senior officials of Saudi Arabia, the United Arab Emirates, the wider Gulf Cooperation Council (GCC), Turkey and the Levant.

The watchlist task summarizes the screen. It has task_name, status, result and reason, and no sources. It comes after the standard tasks and any other add-on tasks; find it by task_name, not by position. The fields every task shares are in The task object.

ResultStatusMeaning
watchlist_no_hitssuccessScreening completed and found no hits. watchlists is [].
watchlist_hitsfailureOne or more hits are listed in watchlists. The list can be partial, when screening ran out of time after finding some hits; see When screening does not complete.
not_completedfailureScreening did not complete and found no hits. This is not a clean screen: retry the request. watchlists is ["Screen API error"] if the screening service was unavailable, or [] if screening timed out.

Branch on result. The reason sentence is for people to read, and its wording can change.

A screening failure does not fail the request. The rest of the response returns as usual with 200, and the watchlist task reports what happened.

  • not_completed is not a clean screen. Retry with backoff. A retry is a new request, with its own response_id. See Retries and backoff.
  • watchlist_hits does not say whether screening finished. Screening may have run out of time, or the screening service may have failed for part of the request, after some hits were found. result is the same for a complete and a partial hit list, so treat any hit list as possibly partial. To check for more hits, rerun the request and compare the hit lists.
  • watchlists can hold a string. Check each item’s type before you read its fields.

When the screening service is unavailable and no hits were found, the response looks like this. It is trimmed to the watchlist task. The matched records in data return as usual and are omitted here.

Example response: screening service unavailable
{
"risk_summary": {
"tasks": [
{
"task_name": "watchlist",
"status": "failure",
"result": "not_completed",
"reason": "Watchlist service is currently unavailable"
}
]
},
"response_id": "2a1b3c4d-5e6f-7890-abcd-ef1234567890",
"watchlists": ["Screen API error"]
}

watchlists is a top-level array, present whenever you request watchlist, at any top_n. Each object is one watchlist hit: a listed entity that resembles a screened name, address or date of birth. It can instead hold the string "Screen API error"; see When screening does not complete.

idstring

Identifies the list entry. Treat it as an opaque string; its format varies (for example ofac/sdn/6365). The same entry can appear in two hits when it matched on different fields.

match_confidencenumber

How closely the listed entity matches the screened input, from 0 to 1. Higher is closer.

watchlist_entityobject

The listed entity. See watchlist_entity.

matched_fieldsobject

The fields that drove the match. See matched_fields.

This hit matched a screened business name to an organization on the World Bank list:

Example watchlist hit
{
"id": "enigma/worldbank/WB_872",
"match_confidence": 0.92,
"watchlist_entity": {
"watchlist_name": "World Bank",
"entity_type": "legal_entity",
"full_name": null,
"organization_name": "ACME CORP LIMITED",
"dob": null,
"full_address": null
},
"matched_fields": {
"name": "ACME CORP LIMITED"
}
}

The listed entity that the hit refers to. Every field is present. watchlist_name and entity_type describe every hit. full_name, organization_name, dob and full_address are filled only when their key is in matched_fields (see the list below). Otherwise they are null, even when the list holds a value.

watchlist_namestring

The list the entry is on. See Lists screened. Can be null.

entity_typestring

person when a person name or date of birth drove the match, otherwise legal_entity. It reflects the matched fields, not the type of the list entry, so a listed person matched only on name or address reports legal_entity. When both name and person_name drove the match, either value can appear.

full_namestring

The listed person’s name, when person_name drove the match; otherwise null. Can be an empty string when the list entry has no person name.

organization_namestring

The listed organization’s name, when name drove the match; otherwise null.

dobstring

The listed person’s date of birth, when date_of_birth drove the match; otherwise null.

full_addressstring

The listed entity’s address, when address drove the match; otherwise null.

An object with one key for each field that drove the match. Each value is the listed entity’s value, not the value you sent, and equals the matching watchlist_entity field.

Key Meaning Same value as
name A screened organization name matched the listed entity’s name. organization_name
person_name A screened person’s name matched a listed person. full_name
address An address matched the listed entity’s address. full_address
date_of_birth A date of birth matched the listed person’s. dob

To see which of your names produced a hit, compare them with these values yourself.

A common false positive is a different business or person with the same name. Each hit carries these fields for comparison:

  • matched_fields holds the listed values that matched, such as a name.
  • match_confidence shows how closely the listed entity matches, from 0 to 1.
  • A hit often carries only a name. The entry on the issuing list can hold more detail, such as date of birth, address or nationality.
  • A PEP hit comes from Enigma’s own compiled list, not an official registry. See PEP coverage.