- Docs
- API reference
- Endpoints and schemas
- KYB API
- Use cases
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.
https://api.enigma.com/v2/kyb/?package=verify&attrs=watchlist,tin_verificationRun 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.
Example
Section titled “Example”This request verifies Enigma Technologies, screens it against watchlists and checks its TIN.
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" }'The response below is trimmed. risk_summary.tasks shows three of the nine
tasks this request runs, and data shows only the fields that identify each
match and link them.
{ "risk_summary": { "tasks": [ { "task_name": "name_verification", "status": "success", "result": "name_exact_match", "reason": "An input business name exactly matches a business name in any of Enigma's records", "sources": [ { "name": "ENIGMA TECHNOLOGIES", "match_entity_type": "brand", "urls": [] } ] }, { "task_name": "domestic_registration", "status": "success", "result": "domestic_active", "reason": "An active domestic registration was found", "sources": [ { "issue_date": "2011-04-26", "file_number": "4973743", "registration_state": "DE", "registered_name": "ENIGMA TECHNOLOGIES, INC." } ] }, { "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", "data": { "registered_entities": [ { "id": "4dccd7a5-790c-c4d1-0000-108000000000", "names": [{ "name": "ENIGMA TECHNOLOGIES, INC." }], "brand_ids": ["5f53e079-c66a-487e-8a9d-08efc39652ee"] } ], "brands": [ { "id": "5f53e079-c66a-487e-8a9d-08efc39652ee", "registered_entity_ids": ["4dccd7a5-790c-c4d1-0000-108000000000"], "names": [{ "name": "ENIGMA TECHNOLOGIES" }] } ] }, "watchlists": []}Parameters
Section titled “Parameters”x-api-keyRequiredYour API key. Send it from your server only. See Authentication.
packageRequiredverify. Runs the seven standard tasks, including the verification tier. Set it explicitly in production.attrsRequiredwatchlist,tin_verification. Addssn_verificationto check an owner’s SSN, ornegative_newsfor negative news. Values are case-sensitive, and a misspelled one is ignored without an error.top_nDefault 1Must be
1: tasks run only at1, andtin_verificationreturns400above it. See Whentop_nis above 1.nameRequiredThe business name: the legal name or a trade name (DBA), or up to two in
names.addressFor the address tasksThe business address, with
street_address1: the address tasks need it.websiteThe business website. It helps tell apart businesses that share a name. See Send strong identifiers.
tinFortin_verificationNine digits once dashes are removed. It is checked against the first business name you send.
personForperson_verificationAn owner’s
first_nameandlast_name, forperson_verification. Withssn_verification, putssnon 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.
Response
Section titled “Response”dataThe match: at most one registered entity and one brand, linked by ID. See The
dataobject.risk_summary.tasks[]The seven standard
verifytasks, thentin_verificationandwatchlist. Find each task bytask_nameand branch on itsresult. See Tasks by package.Show the result values of the nine tasks
Task Results name_verificationname_exact_match,name_match,name_not_verifiedsos_name_verificationname_exact_match,name_match,name_not_verifiedaddress_verificationaddress_exact_match,address_match,address_not_verifiedsos_address_verificationaddress_exact_match,address_match,address_not_verifieddomestic_registrationdomestic_active,domestic_unknown,domestic_inactive,domestic_not_foundperson_verificationperson_match,person_not_verifiedverification_tiertier_1,tier_2,tier_3,tier_unknowntin_verificationtin_verified,tin_not_verified,tin_not_issued,tin_invalid,duplicate,not_completedwatchlistwatchlist_no_hits,watchlist_hits,not_completedwatchlistsOne object per watchlist hit, or
[]when screening found none. See Watchlist hits.response_idThe ID of this response. See Top-level fields.
New result values can appear, so handle a value your code does not recognize.
Read the result
Section titled “Read the result”Read the response in this order:
- The match in
data. An emptydata.registered_entitiesmeans no registered entity matched, and the request still returns200. See When nothing matches. Join the brand to the registered entity by ID, as in Which record is the match. - The task results. Find each task by
task_nameand branch on itsresult, using the values listed under Response. - The
watchlisttask andwatchlists. A hit does not say which name or record produced it, and a hit is not a confirmed match. See Interpret a hit.
What to read in the example
Section titled “What to read in the example”risk_summary.tasks. All three tasks have the statussuccess, and their results arename_exact_match,domestic_activeandwatchlist_no_hits.sourcesshows the Enigma records behind each result; thewatchlisttask has none, because its hits are inwatchlists.data. One registered entity and one brand. Each lists the other’sidinbrand_idsandregistered_entity_ids.watchlists. Empty, because no listed entity resembled a screened name. Thewatchlisttask reports the same result.
Before you rely on it
Section titled “Before you rely on it”- Account enablement.
watchlist,tin_verificationand 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 a504. See Retry after a 200. - IRS outages. A
tin_verificationresult ofnot_completedusually means the IRS was unavailable. See When the IRS is unavailable. - Incomplete screening. A
watchlistresult ofnot_completedis 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_idfor every request, and quote it when you contact Enigma support. See Conventions.
Related
Section titled “Related”- Screen a person: the person-only request to send for each owner.
- Get negative news: add negative news and poll for results that arrive later.
- Response object: every field in the response.
- How checks work: every task and its results.