- Docs
- API reference
- Endpoints and schemas
- KYB API
- Checks
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.
{ "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" } } ]}A business screen of Enigma Technologies that found no hits, trimmed to the
watchlist task.
{ "risk_summary": { "tasks": [ { "task_name": "watchlist", "status": "success", "result": "watchlist_no_hits", "reason": "No hits were identified on the consolidated sanctions list (including OFAC)" } ] }, "response_id": "2a1b3c4d-5e6f-7890-abcd-ef1234567890", "watchlists": []}What is screened
Section titled “What is screened”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.
Lists screened
Section titled “Lists screened”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.
PEP coverage
Section titled “PEP coverage”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
Section titled “The watchlist task”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.
| Result | Status | Meaning |
|---|---|---|
watchlist_no_hits | success | Screening completed and found no hits. watchlists is []. |
watchlist_hits | failure | One 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_completed | failure | Screening 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.
When screening does not complete
Section titled “When screening does not complete”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_completedis not a clean screen. Retry with backoff. A retry is a new request, with its ownresponse_id. See Retries and backoff.watchlist_hitsdoes 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.resultis 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.watchlistscan 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.
{ "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"]}Watchlist hits
Section titled “Watchlist hits”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.
idIdentifies 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_confidenceHow closely the listed entity matches the screened input, from
0to1. Higher is closer.watchlist_entityThe listed entity. See
watchlist_entity.matched_fieldsThe fields that drove the match. See
matched_fields.
This hit matched a screened business name to an organization on the World Bank list:
{ "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 watchlist_entity object
Section titled “The watchlist_entity object”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_nameThe list the entry is on. See Lists screened. Can be
null.entity_typepersonwhen a person name or date of birth drove the match, otherwiselegal_entity. It reflects the matched fields, not the type of the list entry, so a listed person matched only on name or address reportslegal_entity. When bothnameandperson_namedrove the match, either value can appear.full_nameThe listed person’s name, when
person_namedrove the match; otherwisenull. Can be an empty string when the list entry has no person name.organization_nameThe listed organization’s name, when
namedrove the match; otherwisenull.dobThe listed person’s date of birth, when
date_of_birthdrove the match; otherwisenull.full_addressThe listed entity’s address, when
addressdrove the match; otherwisenull.
The matched_fields object
Section titled “The matched_fields object”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.
Interpret a hit
Section titled “Interpret a hit”A common false positive is a different business or person with the same name. Each hit carries these fields for comparison:
matched_fieldsholds the listed values that matched, such as a name.match_confidenceshows how closely the listed entity matches, from0to1.- 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
PEPhit comes from Enigma’s own compiled list, not an official registry. See PEP coverage.
Related
Section titled “Related”- How checks work: the
watchlisttask beside the other checks. - Screen a business and Screen a person: the requests, with example responses.
- Add-ons: add-on tasks, attribute-only requests and account enablement.
- Response object: where
watchlistssits in the response. - Errors and rate limits: retries and timeouts.