Skip to content
Console(opens in a new tab)

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.

Example response
{
"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"
}
]
}
}

This table lists every task and the results it can return. Each task name links to its full definition.

TaskResults
address_verificationaddress_exact_match, address_match, address_not_verified
sos_address_verificationaddress_exact_match, address_match, address_not_verified
name_verificationname_exact_match, name_match, name_not_verified
sos_name_verificationname_exact_match, name_match, name_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
ssn_verificationssn_verified, ssn_not_verified, ssn_not_issued, ssn_invalid, duplicate, not_completed
tin_verificationtin_verified, tin_not_verified, tin_not_issued, tin_invalid, duplicate, not_completed
watchlistwatchlist_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_verification and sos_address_verification compare the names and addresses you send with the matched records. They run on both packages.
  • Registration and person checks. domestic_registration reports whether the matched registered entity is registered in its home state, and person_verification compares the person you send with the people named on its registrations. They run on verify only.
  • TIN and SSN checks. tin_verification and ssn_verification are add-ons that check a number and a name against IRS records.
  • Verification tier Beta. verification_tier grades how independently the matched business’s existence can be corroborated. It compares nothing you sent. Its page covers when it runs, the criteria object and how to read the verification tier.
  • Watchlist screening. The watchlist add-on screens names connected to the business against sanctions, debarment and PEP lists, and summarizes the hits returned in the top-level watchlists array. 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-level background_task object, and the results that are not ready when the POST returns come from GET /v2/kyb/{task_id}.

Each entry in risk_summary.tasks has these fields.

task_namestring

The task. One of the ten names in Tasks by package.

statusstring

A coarse outcome: success or failure. verification_tier always reports success. For tin_verification and ssn_verification, see TIN and SSN checks.

resultstring

The specific outcome, such as name_exact_match or domestic_inactive. Each task’s possible values are in Every check at a glance.

reasonstring

A sentence that explains the result, for people to read. The wording can change.

sourcesarray of object

The Enigma records behind the result. The shape depends on the task; see Sources. Present on every task except verification_tier and watchlist.

criteriaobject

The signals behind a verification tier. Present on verification_tier only.

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.

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 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.

namestring

On name tasks, the name on record that matched. On person_verification, the registered person’s full name. On tin_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_typestring

Where the matching record came from: registered_entity or brand. Always registered_entity on the SoS tasks and on person_verification.

urlsarray of string

Source URLs for the records behind the match, sorted. Always present on name_verification and address_verification sources, and [] when no URL is available. Brand sources always have [].

addressobject

The address on record that matched: street_address1, street_address2, city, state and postal_code, plus type, deliverable, virtual, delivery_type and rdi when the record has them. See Addresses.

match_relationship_typestring

How the matched address relates to its record. See match_relationship_type values. Omitted when unknown.

registration_statestring or null

The state of the active domestic registration found by domestic_registration.

registered_namestring or null

The business name on that registration.

file_numberstring or null

The SoS file number of that registration.

issue_datestring or null

The date that registration was issued, as YYYY-MM-DD.

tinstring

The TIN of the reported pair, echoed back. See Name and TIN pairs.

ssnstring

The SSN you sent, echoed back in full.

first_namestring

On 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_namestring

On ssn_verification, the last name associated with the checked SSN, when available. Omitted when there is no value.

date_of_birthstring

On ssn_verification, the date of birth associated with the checked SSN, when available. Omitted when there is no value.

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.