- Docs
- API reference
- Endpoints and schemas
- KYB API
- Use cases
Screen a business
Screen a business, and the people named on its registrations, against sanctions, debarment and PEP lists.
https://api.enigma.com/v2/kyb/?package=verify&attrs=watchlistScreen 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.
Example
Section titled “Example”This request verifies Enigma Technologies and screens it:
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" } }'Screening found no hits. The response is trimmed to the watchlist task,
which follows the seven standard tasks, and omits data. See
Response object for a
complete response.
{ "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": []}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. See
When screening does not complete.
{ "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"]}Parameters
Section titled “Parameters”x-api-keyRequiredYour API key. Send it from your server only. See Authentication.
attrsRequiredwatchlist, 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_nDefault 11for this use case. Above1, thewatchlistsarray still returns, but there is nowatchlisttask.packageDefaultverifyThe package:
identifyorverify. Case-insensitive. Set it explicitly in production. Cannot be combined withproducts.
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.
Response
Section titled “Response”risk_summary.tasks[]The
watchlisttask, after the package’s standard tasks and any other add-on tasks. Find the task bytask_name, not by position, and branch on itsresult. See Thewatchlisttask.Show the 3 result values
watchlist_no_hitssuccess- Screening completed and found no hits.
watchlistsis[]. 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.
watchlistsis["Screen API error"]if the screening service was unavailable, or[]if screening timed out.
watchlistsOne object per watchlist hit, or
[]when screening found none. Present whenever you requestwatchlist, at anytop_n. See Watchlist hits.
Request forms
Section titled “Request forms”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. |
Before you rely on it
Section titled “Before you rely on it”- Account enablement.
watchlistis an add-on; see Account enablement. - Case-sensitive values. A request with
attrs=Watchlistruns no screening and still returns200. Check that thewatchlisttask is inrisk_summary.tasks. See Query parameters. - Keep
top_n=1. Without thewatchlisttask, an emptywatchlistsarray cannot tell you whether screening finished. See Whentop_nis above 1. - Incomplete screens.
not_completedis not a clean screen, and awatchlist_hitslist 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.
Related
Section titled “Related”- Watchlist screening: what is screened, the lists screened, and the hit object.
- Screen a person: screen one individual, such as an owner, without a business.
- Onboard a business: screening together with verification and an IRS check of the TIN.