Skip to content
Console(opens in a new tab)

Screen a business

Screen a business, and the people named on its registrations, against sanctions, debarment and PEP lists.

POSThttps://api.enigma.com/v2/kyb/?package=verify&attrs=watchlist

Screen a business against sanctions, debarment and politically exposed person (PEP) lists. Add watchlist to attrs on an identify or verify request, and Enigma matches the business and screens it in the same call: like every use case, it is one POST /v2/kyb/ request, and add-ons combine, for example attrs=watchlist,tin_verification, as Onboard a business does.

This request verifies Enigma Technologies and screens it:

cURL
curl --request POST "https://api.enigma.com/v2/kyb/?package=verify&attrs=watchlist&top_n=1" \
--header "x-api-key: $ENIGMA_API_KEY" \
--header "Content-Type: application/json" \
--data '{
"name": "Enigma Technologies",
"website": "https://enigma.com",
"address": {
"street_address1": "245 5th Ave",
"city": "New York",
"state": "NY",
"postal_code": "10016"
}
}'
x-api-keyheaderRequired

Your API key. Send it from your server only. See Authentication.

attrsqueryRequired

watchlist, alone or with other add-ons. Must be enabled for your account. Values are case-sensitive, and a misspelled one is ignored without an error.

top_nqueryDefault 1

1 for this use case. Above 1, the watchlists array still returns, but there is no watchlist task.

packagequeryDefault verify

The package: identify or verify. Case-insensitive. Set it explicitly in production. Cannot be combined with products.

The body is the business input of any request. Enigma screens each business name you send, the registered entities it finds for your input, and the people and organizations named on their registrations; see What is screened. A person you send with the business is used for matching and is not guaranteed to be screened. To screen an owner or applicant, send a separate Screen a person request. All body fields are in Request body, and the rules in Validation.

risk_summary.tasks[]array

The watchlist task, after the package’s standard tasks and any other add-on tasks. Find the task by task_name, not by position, and branch on its result. See The watchlist task.

Show the 3 result values
watchlist_no_hitssuccess
Screening completed and found no hits. watchlists is [].
watchlist_hitsfailure
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_completedfailure
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.
watchlistsarray

One object per watchlist hit, or [] when screening found none. Present whenever you request watchlist, at any top_n. See Watchlist hits.

At top_n=1, the request form sets what comes back:

Request What you get
attrs=watchlist The standard tasks, then the watchlist task, and the watchlists array.
products=watchlist An attribute-only request: the matched IDs, the watchlist task and the watchlists array. No standard tasks.
  • Account enablement. watchlist is an add-on; see Account enablement.
  • Case-sensitive values. A request with attrs=Watchlist runs no screening and still returns 200. Check that the watchlist task is in risk_summary.tasks. See Query parameters.
  • Keep top_n=1. Without the watchlist task, an empty watchlists array cannot tell you whether screening finished. See When top_n is above 1.
  • Incomplete screens. not_completed is not a clean screen, and a watchlist_hits list can be partial. See When screening does not complete.
  • A hit is not a confirmed match. A hit means a listed entity resembles a screened name, address or date of birth. See Interpret a hit.