- Docs
- API reference
- Endpoints and schemas
- KYB API
- Checks
How checks work
What a KYB check is, every check and its results at a glance, the task object, the checks each package runs, and the sources behind each result.
A check is one task in risk_summary.tasks: one verification of the business
Enigma matched. Most tasks compare something you sent, such as a name or an
address, with Enigma’s records (or, for identity numbers, IRS records), and
every task reports its outcome in a result that your code can branch on.
Your package decides the
standard tasks, and add-on tasks
add more. Every standard task in your package is always present: if you did
not send the input a task needs, the task returns a failure result instead of
being left out. Add-on tasks appear only when you request them, and no task
runs unless top_n is 1, the default.
This example verify response is trimmed to three tasks, with their sources
left out; Sources describes them, and each check’s own page shows
its sources in full.
{ "risk_summary": { "tasks": [ { "task_name": "address_verification", "status": "success", "result": "address_match", "reason": "An input address matches an address in any of Enigma's records" }, { "task_name": "name_verification", "status": "success", "result": "name_match", "reason": "An input business name matches a business name in any of Enigma's records" }, { "task_name": "domestic_registration", "status": "success", "result": "domestic_active", "reason": "An active domestic registration was found" } ] }}Every check at a glance
Section titled “Every check at a glance”This table lists every task and the results it can return. Each task name links to its full definition.
| Task | Results |
|---|---|
address_verification | address_exact_match, address_match, address_not_verified |
sos_address_verification | address_exact_match, address_match, address_not_verified |
name_verification | name_exact_match, name_match, name_not_verified |
sos_name_verification | name_exact_match, name_match, name_not_verified |
domestic_registration | domestic_active, domestic_unknown, domestic_inactive, domestic_not_found |
person_verification | person_match, person_not_verified |
verification_tier | tier_1, tier_2, tier_3, tier_unknown |
ssn_verification | ssn_verified, ssn_not_verified, ssn_not_issued, ssn_invalid, duplicate, not_completed |
tin_verification | tin_verified, tin_not_verified, tin_not_issued, tin_invalid, duplicate, not_completed |
watchlist | watchlist_no_hits, watchlist_hits, not_completed |
The checks fall into six families, each with its own page:
- Name and address checks.
name_verification,sos_name_verification,address_verificationandsos_address_verificationcompare the names and addresses you send with the matched records. They run on both packages. - Registration and person checks.
domestic_registrationreports whether the matched registered entity is registered in its home state, andperson_verificationcompares the person you send with the people named on its registrations. They run onverifyonly. - TIN and SSN checks.
tin_verificationandssn_verificationare add-ons that check a number and a name against IRS records. - Verification tier Beta.
verification_tiergrades how independently the matched business’s existence can be corroborated. It compares nothing you sent. Its page covers when it runs, thecriteriaobject and how to read the verification tier. - Watchlist screening.
The
watchlistadd-on screens names connected to the business against sanctions, debarment and PEP lists, and summarizes the hits returned in the top-levelwatchlistsarray. Its page covers what is screened, the lists and the hit object. - Negative news. An add-on
attribute that adds no task to
risk_summary.tasks. Its articles arrive in a top-levelbackground_taskobject, and the results that are not ready when the POST returns come fromGET /v2/kyb/{task_id}.
The task object
Section titled “The task object”Each entry in risk_summary.tasks has these fields.
task_nameThe task. One of the ten names in Tasks by package.
statusA coarse outcome:
successorfailure.verification_tieralways reportssuccess. Fortin_verificationandssn_verification, see TIN and SSN checks.resultThe specific outcome, such as
name_exact_matchordomestic_inactive. Each task’s possible values are in Every check at a glance.reasonA sentence that explains the result, for people to read. The wording can change.
sourcesThe Enigma records behind the result. The shape depends on the task; see Sources. Present on every task except
verification_tierandwatchlist.criteriaThe signals behind a verification tier. Present on
verification_tieronly.
Tasks by package
Section titled “Tasks by package”The identify package runs four standard tasks, and verify (the default)
adds three more. Add-on tasks run on either package when you name them in
attrs by the task’s own name (or in products on an attribute-only
request), and must be enabled for your account. See
Packages and
Add-ons.
| Task | Runs on | Checks |
|---|---|---|
address_verification |
identify, verify |
A submitted address against every address on the matched records. |
sos_address_verification |
identify, verify |
A submitted address against Secretary of State (SoS) registration addresses only. |
name_verification |
identify, verify |
A submitted business name against registration and brand names. |
sos_name_verification |
identify, verify |
A submitted business name against SoS registration names only. |
domestic_registration |
verify |
Whether the matched registered entity has a registration in its home state, and its status. |
person_verification |
verify |
The submitted person against the people named on the matched registrations. |
verification_tier Beta |
verify |
How independently the business’s existence can be corroborated. |
ssn_verification |
Add-on | A person’s SSN and name against IRS records. |
tin_verification |
Add-on | A business TIN and name against IRS records. |
watchlist |
Add-on | Names connected to the business against sanctions, debarment and PEP lists. |
Tasks appear in the order of this table. Find a task by task_name, not by its
position in the array.
When the task list changes
Section titled “When the task list changes”| Case | Effect on risk_summary |
|---|---|
top_n greater than 1 |
No risk_summary key, so no tasks. See When top_n is above 1. |
Attribute-only request (products) |
Only the add-on tasks your products values add: watchlist, tin_verification, ssn_verification. tasks is [] when none of them is requested. |
| No match | data.registered_entities and data.brands are both empty. Every task is still present. The name, address and person tasks return their not-verified results, domestic_registration returns domestic_not_found, and verification_tier returns tier_unknown. |
| Brand match only | data.registered_entities is empty but data.brands is not. name_verification and address_verification can succeed against the brand’s names and operating locations. The SoS tasks and person_verification return their not-verified results, and domestic_registration returns domestic_not_found. |
| Person-only screen | The package’s standard tasks return their not-verified results, as when no business matched, followed by watchlist. See Screen a person without a business. |
Sources
Section titled “Sources”sources lists the Enigma records behind a task’s result. It is [] when
nothing matched. The fields in each entry depend on the task.
| Task | Fields in each source | When sources has entries |
|---|---|---|
name_verification |
name, match_entity_type, urls |
On a match result. |
sos_name_verification |
name, match_entity_type |
On a match result. |
address_verification |
address, match_entity_type, match_relationship_type, urls |
On a match result. |
sos_address_verification |
address, match_entity_type, match_relationship_type |
On a match result. |
person_verification |
name, match_entity_type |
On person_match. |
domestic_registration |
registration_state, registered_name, file_number, issue_date |
On domestic_active only. |
tin_verification |
tin, name |
Whenever the check returned a result for the reported name and TIN pair, including on some failure results. |
ssn_verification |
ssn, first_name, last_name, date_of_birth |
Whenever the check returned a result for the number you sent, including on some failure results. |
When a name or address task finds an exact match, sources lists only the
exact matches. Otherwise it lists every record that matched. The same record
can appear more than once when more than one submitted name or address matched
it.
Source fields
Section titled “Source fields”nameOn name tasks, the name on record that matched. On
person_verification, the registered person’s full name. Ontin_verification, a business name associated with the checked TIN, when one is available. It is not a result from the IRS and is not evidence that the name matched.match_entity_typeWhere the matching record came from:
registered_entityorbrand. Alwaysregistered_entityon the SoS tasks and onperson_verification.urlsSource URLs for the records behind the match, sorted. Always present on
name_verificationandaddress_verificationsources, and[]when no URL is available. Brand sources always have[].addressThe address on record that matched:
street_address1,street_address2,city,stateandpostal_code, plustype,deliverable,virtual,delivery_typeandrdiwhen the record has them. See Addresses.match_relationship_typeHow the matched address relates to its record. See
match_relationship_typevalues. Omitted when unknown.registration_stateThe state of the active domestic registration found by
domestic_registration.registered_nameThe business name on that registration.
file_numberThe SoS file number of that registration.
issue_dateThe date that registration was issued, as
YYYY-MM-DD.tinThe TIN of the reported pair, echoed back. See Name and TIN pairs.
ssnThe SSN you sent, echoed back in full.
first_nameOn
ssn_verification, the first name associated with the checked SSN, when available. It is not a result from the IRS. Omitted when there is no value.last_nameOn
ssn_verification, the last name associated with the checked SSN, when available. Omitted when there is no value.date_of_birthOn
ssn_verification, the date of birth associated with the checked SSN, when available. Omitted when there is no value.
match_relationship_type values
Section titled “match_relationship_type values”| Value | Meaning |
|---|---|
registration_address |
An address on an SoS registration. |
mailing_address |
A mailing address, either a registration address of type mailing or one of the registered entity’s own mailing addresses. |
operating_location_address |
The address of one of the brand’s operating locations. |
When the same address is on a registration and among the registered entity’s
mailing addresses, the source reports registration_address.
Related
Section titled “Related”- Response object: where
risk_summarysits in the response. - Packages and Add-ons: which tasks each request runs.
POST /v2/kyb/: the inputs each task compares.- Errors and rate limits: retrying requests safely.