Skip to content
Console(opens in a new tab)

Onboard a business

Run the check most onboarding flows need: verify a business, screen it against watchlists and check its TIN in one request, then screen each owner.

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

Run the full check most onboarding flows need in one request: match the business, check its registration standing and the people on its filings, get its verification tier, screen it against watchlists and check its TIN with the IRS. This request combines Verify a business, Screen a business and Verify a TIN or SSN: like every use case, it is one POST /v2/kyb/ request, and add-ons combine. Then screen each owner with a separate person-only request.

This request verifies Enigma Technologies, screens it against watchlists and checks its TIN.

cURL
curl --request POST "https://api.enigma.com/v2/kyb/?package=verify&attrs=watchlist,tin_verification&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"
},
"person": {
"first_name": "Jane",
"last_name": "Smith"
},
"tin": "123456789"
}'
x-api-keyheaderRequired

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

packagequeryRequired

verify. Runs the seven standard tasks, including the verification tier. Set it explicitly in production.

attrsqueryRequired

watchlist,tin_verification. Add ssn_verification to check an owner’s SSN, or negative_news for negative news. Values are case-sensitive, and a misspelled one is ignored without an error.

top_nqueryDefault 1

Must be 1: tasks run only at 1, and tin_verification returns 400 above it. See When top_n is above 1.

namebodyRequired

The business name: the legal name or a trade name (DBA), or up to two in names.

addressbody, objectFor the address tasks

The business address, with street_address1: the address tasks need it.

websitebody

The business website. It helps tell apart businesses that share a name. See Send strong identifiers.

tinbodyFor tin_verification

Nine digits once dashes are removed. It is checked against the first business name you send.

personbody, objectFor person_verification

An owner’s first_name and last_name, for person_verification. With ssn_verification, put ssn on the person object.

The person sent with a business request is used for matching and person_verification; screening of that person is not guaranteed. To screen each owner, send one person-only screen per owner. All body fields are in Request body, and the rules in Validation.

dataobject

The match: at most one registered entity and one brand, linked by ID. See The data object.

risk_summary.tasks[]array

The seven standard verify tasks, then tin_verification and watchlist. Find each task by task_name and branch on its result. See Tasks by package.

Show the result values of the nine tasks
TaskResults
name_verificationname_exact_match, name_match, name_not_verified
sos_name_verificationname_exact_match, name_match, name_not_verified
address_verificationaddress_exact_match, address_match, address_not_verified
sos_address_verificationaddress_exact_match, address_match, address_not_verified
domestic_registrationdomestic_active, domestic_unknown, domestic_inactive, domestic_not_found
person_verificationperson_match, person_not_verified
verification_tiertier_1, tier_2, tier_3, tier_unknown
tin_verificationtin_verified, tin_not_verified, tin_not_issued, tin_invalid, duplicate, not_completed
watchlistwatchlist_no_hits, watchlist_hits, not_completed
watchlistsarray

One object per watchlist hit, or [] when screening found none. See Watchlist hits.

response_idstring

The ID of this response. See Top-level fields.

New result values can appear, so handle a value your code does not recognize.

Read the response in this order:

  1. The match in data. An empty data.registered_entities means no registered entity matched, and the request still returns 200. See When nothing matches. Join the brand to the registered entity by ID, as in Which record is the match.
  2. The task results. Find each task by task_name and branch on its result, using the values listed under Response.
  3. The watchlist task and watchlists. A hit does not say which name or record produced it, and a hit is not a confirmed match. See Interpret a hit.
  • risk_summary.tasks. All three tasks have the status success, and their results are name_exact_match, domestic_active and watchlist_no_hits. sources shows the Enigma records behind each result; the watchlist task has none, because its hits are in watchlists.
  • data. One registered entity and one brand. Each lists the other’s id in brand_ids and registered_entity_ids.
  • watchlists. Empty, because no listed entity resembled a screened name. The watchlist task reports the same result.
  • Account enablement. watchlist, tin_verification and the optional add-ons must be enabled for your account. See Account enablement.
  • TIN duplicates. Resending the same TIN within a short window returns duplicate, including after a 504. See Retry after a 200.
  • IRS outages. A tin_verification result of not_completed usually means the IRS was unavailable. See When the IRS is unavailable.
  • Incomplete screening. A watchlist result of not_completed is not a clean screen. See When screening does not complete.
  • Time limit. A request that takes longer than about 29 seconds returns 504. See Timeouts.
  • Response ID. Log response_id for every request, and quote it when you contact Enigma support. See Conventions.