KYB Response Task Results

Each task compares a value you provided in your request to the corresponding value in either the Enigma data set or the records of the authoritative Secretary of State (SoS). For an overview of all tasks and how to combine their results into approval decisions, see Making Decisions with Task Results.

All task results, except the watchlist task result, include a sources array in the response that specifies which Enigma records matched the input value. The shape of each source entry depends on the task type:

Name verification tasks (name_verification, sos_name_verification, person_verification) return entries with:

Field	Type	Description
`name`	string	The name value in Enigma's records that matched the submitted input.
`match_entity_type`	string	The type of entity the match came from. Either `"brand"` (matched a brand name) or `"registered_entity"` (matched a name on an SoS registration).

"sources": [
  {
    "name": "ENIGMA TECHNOLOGIES",
    "match_entity_type": "brand"
  },
  {
    "name": "ENIGMA TECHNOLOGIES, INC.",
    "match_entity_type": "registered_entity"
  }
]

Address verification tasks (address_verification, sos_address_verification) return entries with:

Field	Type	Description
`address`	object	The address in Enigma's records that matched the submitted input. Contains `street_address1`, `street_address2`, `city`, `state`, and `postal_code`.
`match_entity_type`	string	The type of entity the match came from. Either `"brand"` (matched a brand address) or `"registered_entity"` (matched an address on an SoS registration).

"sources": [
  {
    "address": {
      "street_address1": "32 MERCER ST",
      "street_address2": "FL 8",
      "city": "NEW YORK",
      "state": "NY",
      "postal_code": "10013"
    },
    "match_entity_type": "registered_entity"
  }
]

See domestic_registration for its distinct sources shape.

When a task fails, sources will be an empty array.

Tasks operate on one match

Task logic can only operate on one matching legal entity and brand at a time, so if you specify a top_n greater than 1, task results will not be returned.

Standard Tasks

Name Verification

The name_verification task compares the business name(s) in the names field of the request to the names in both the registered entity and brand objects returned in the response. The name_verification task will return one of the following results:

Status	Result	Reason
Success	`name_exact_match`	An input business name exactly matches a business name in any of Enigma records
Success	`name_match`	An input business name matches a business name in any of Enigma records
Failure	`name_not_verified`	No input business name matches a business name in any of Enigma records

An input name is an exact match only if it is nearly identical to the matching name. Only minor differences, such as capitalization, can exist between the input name and the name that matched. For example, "Enigma Technologies" would be considered an exact match to "Enigma technologies".

A name is a match, but not an exact match, if it is substantially similar to the name that matched, but not identical. The most common reason for a non-exact name match is a difference in the legal suffix between the submitted name and the name that matched. For example, "Enigma Technologies" would be considered a match, but not an exact match, to "Enigma Technologies Inc.".

Typically, customers consider any name match to the submitted business name to be verified for compliance programs, even if it isn't exact, so they base their decisioning logic on the status field. If your use case calls for more granular decision making, use the result field to distinguish between exact and non-exact matches.

The name_verification task is included in both the identify and verify packages.

SoS Name Verification

The matching logic for the sos_name_verification task is the same as the matching logic for the name_verification task. The difference is that the sos_name_verification task only compares the business name(s) in the names field of the request to the names in the registered entity returned in the response. No other records are eligible to match the submitted name(s).

The sos_name_verification task will return one of the following results:

Status	Result	Reason
Success	`name_exact_match`	An input business name exactly matches a business name on a matching SoS registration
Success	`name_match`	An input business name matches a business name on a matching SoS registration
Failure	`name_not_verified`	No input business name matches any business names on a matching SoS registration

The sos_name_verification task is included in both the identify and verify packages.

Address Verification

The address_verification task compares the address(es) in the addresses field of the request to the addresses in both the registered entities and brands objects returned in the response. The address_verification task will return one of the following results:

Status	Result	Reason
Success	`address_exact_match`	An input address exactly matches an address in any of Enigma records
Success	`address_match`	An input address matches an address in any of Enigma records
Failure	`address_not_verified`	No input address matches any address in any of Enigma records

An input address is an exact match if all of its components are substantially the same as the matching address. Only minor differences, such as a difference in the number of digits specified in the postal code, will still result in an exact match. Note that if any input value for street_address2 is provided, then matching address must include the same value for street_address2 in order to be considered an exact match, but if no input value for street_address2 is provided, then the matching address can have a street_address2 value and still be considered an exact match.

An input address is a match, but not an exact match, even if certain components of the input address are different from the matching address, as long as the address as a whole is substantially similar. For instance, the city value may be matched either on the basis of string similarity or on the basis of alternative "vanity" names for the same city, as long as the postal code also matches. For example, "Hollywood" will match to "Los Angeles" as long as a postal code associated with Los Angeles, such as 90027, is also provided in the request.

Typically, customers consider any address match to the submitted address to be verified for compliance programs, even if it isn't exact. The most common reason that an address does not match exactly is when the submitted address and the address that matched are the same, except one is simply missing a suite number. If your use case calls for more granular decision making, you can use the result field to distinguish between exact and non-exact matches.

The address_verification task is included in both the identify and verify packages.

SoS Address Verification

The matching logic for the sos_address_verification task is the same as the matching logic for the address_verification task. The difference is that the sos_address_verification task only compares the address(es) in the addresses field of the request to the addresses in the registered entity returned in the response. No other records are eligible to match the submitted address(es).

The sos_address_verification task will return one of the following results:

Status	Result	Reason
Success	`address_exact_match`	An input address exactly matches an address on a matching SoS registration
Success	`address_match`	An input address matches an address on a matching SoS registration
Failure	`address_not_verified`	No input address matches any address on a matching SoS registration

The sos_address_verification task is included in both the identify and verify packages.

Person Verification

The person_verification task compares the names in the persons field of the request to the names of each person included in the registered entity returned in the response. A person name is a match if two conditions are met:

The full string of the last_name exactly matches the last name of a person on a matching SoS registration
The first character of the first_name matches the first initial of a person on a matching SoS registration

Capitalization and punctuation do not affect the match result.

Do not include any suffixes, initials, honorifics, or other name variations in the first_name or last_name fields of the request. If included, they will be used in the match comparison and may cause the match to fail.

The person_verification task will return one of the following results:

Status	Result	Reason
Success	`person_match`	The person name matches a person name on a matching SoS registration
Failure	`person_not_verified`	The person name does not match any person names on a matching SoS registration

The person_verification task is only included in the verify package.

Domestic Registration

Legal entities must register with the SoS in every state that they operate in. A "domestic" registration is one that is filed in the state where the legal entity was originally registered. A "foreign" registration is one that is filed in a state other than the state where the legal entity was originally registered. For example, a corporation may be registered in Delaware and operate in New York and California, filing registrations in each state. This legal entity's registration in Delaware would be considered "domestic", while its registrations in NY and CA would be considered "foreign".

The domestic_registration task checks whether the matched entity has an active domestic registration on file — that is, a registration filed in the entity's home jurisdiction. The state value in your request affects which entity is matched, but the task itself does not check whether the domestic registration is in that specific state.

The domestic_registration task will return one of the following results:

Status	Result	Reason
Success	`domestic_active`	An active domestic registration was found
Success	`domestic_unknown`	A domestic registration was found but no status was provided by the SoS
Failure	`domestic_inactive`	An inactive domestic registration was found
Failure	`domestic_not_found`	No domestic registration was found

The sources array for this task has a different shape than other tasks. Each entry identifies the specific registration that was found:

Field	Description
`registration_state`	The state where the domestic registration was filed.
`registered_name`	The business name as it appears on the registration.
`file_number`	The SoS file number for the registration.
`issue_date`	The date the registration was issued, formatted YYYY-MM-DD.

The domestic_registration task is only included in the verify package.

Add-On Tasks

Add-on tasks are not included in either package, but can be added to either package. Contact us to discuss including an add-on task in your plan.

Once an add-on task has been added to your plan, you can request it by passing the name of the task in the attrs parameter. For example, to request SSN verification, you can pass ssn_verification in the attrs parameter, like so:

--request POST 'https://api.enigma.com/v2/kyb/?package=verify&attrs=ssn_verification'

SSN Verification

Verifying that a Social Security Number (SSN) and name combination matches Internal Revenue Service (IRS) records is a common step in many Know Your Business (KYB) workflows. For example, you may want to verify that the SSN that an Ultimate Beneficial Owner (UBO) has supplied is in fact their own.

When you request SSN verification, Enigma will verify that a person's SSN is valid and that it matches their last name. Specifically, Enigma will verify that the ssn and the last_name fields of the person object in the request match the information the IRS has on file via the IRS TIN Matching system. When requesting SSN verification, ensure that:

There is only one person provided, and
The SSN is valid and correctly formatted by confirming that:
- It is a 9-digit string
- It has not been stripped of leading zeros
- It does not include any dashes

The ssn_verification task will return one of the following results:

Status	Result	Reason
Success	`ssn_verified`	The SSN and last name combination matches IRS records
Failure	`ssn_invalid`	The SSN is invalid
Failure	`not_completed`	The IRS is unavailable
Failure	`ssn_not_verified`	The SSN and last name combination does not match IRS records
Failure	`ssn_not_verified`	The SSN is not currently issued

If you unexpectedly receive a ssn_invalid result, confirm that the submitted SSN is formatted correctly.

If you receive a not_completed result, the IRS TIN Matching system was unavailable at the time of the request. The IRS can be unavailable for anywhere from a few minutes to several hours. To handle this:

Check TIN Verification on the Enigma status page — it is updated when the IRS TIN Matching system has been unavailable for more than 5 minutes.
If the outage is short, retry the request using exponential backoff: wait 1 minute before the first retry, then 2 minutes, then 4 minutes, up to a maximum of 30 minutes between retries.
If the outage is prolonged or retrying is not practical for your workflow, fall back to document-based verification: request the applicant's SSN card or a recent tax document (e.g. a W-2 or 1099) and complete verification manually.

What is an SSN?

A SSN is a type of tax identification number (TIN) for a person that is used by the Social Security Administration and the IRS. A SSN is assigned at birth, or during the immigration process. While SSNs were designed to be unique, there have been rare instances of duplicate assignments. Enigma also verifies Individual Taxpayer Identification Numbers (ITIN) against submitted persons.

For information on how to verify an Employer Identification Number (EIN) or TIN against a submitted business name, see the TIN Verification task.

TIN (EIN) Verification

A Tax Identification Number (TIN) is used by the Internal Revenue Service (IRS) to uniquely identify a tax paying entity. It can be an Employer Identification Number (EIN), a Social Security Number (SSN), an Individual Taxpayer Identification Number (ITIN), as well as other less common TIN types.

The tin_verification task verifies that the submitted EIN is valid and that it matches the first name in the names object of the request.

When multiple names are submitted, only the first name in the names array is used for TIN verification. If you want to verify against a different name — for example, when you know the legal name but also submitted a DBA — pass primary_name in the request body to specify which name to check:

{
  "primary_name": "Enigma Technologies Inc",
  "data": {
    "names": ["Enigma Technologies Inc", "Enigma"],
    "tins": ["123456789"]
  }
}

In this example, tin_verification will only check whether "Enigma Technologies Inc" matches the submitted EIN. "Enigma" is still used for entity matching but excluded from the TIN check.

When submitting a TIN, ensure that it is valid and correctly formatted by confirming that:

It is a 9-digit string
It has not been stripped of any leading zeros
It does not include any dashes

The tin_verification task will return one of the following results:

Status	Result	Reason
Success	`tin_verified`	The TIN and Name combination matches IRS records
Failure	`tin_invalid`	The TIN is invalid
Failure	`not_completed`	The IRS is unavailable
Failure	`not_completed`	Duplicate TIN matching request
Failure	`tin_not_verified`	The TIN and Name combination does not match IRS records
Failure	`tin_not_verified`	The TIN is not currently issued

If you unexpectedly receive a tin_invalid result, first confirm that the submitted TIN is formatted correctly.

If you receive a not_completed result, the cause is one of two things:

IRS unavailable — The IRS TIN Matching system was temporarily down. Check TIN Verification on the Enigma status page — it is updated when the IRS has been unavailable for more than 5 minutes. Retry using exponential backoff: wait 1 minute before the first retry, then 2 minutes, then 4 minutes, up to a maximum of 30 minutes between retries. If the outage is prolonged, fall back to document-based verification (e.g. request the business's IRS EIN assignment letter or a recent tax filing).
Duplicate TIN request — The same TIN was submitted in two requests within a short window. The IRS TIN Matching system rejects duplicate lookups. Wait at least 60 seconds before resubmitting.

Watchlist (OFAC Sanctions) Screening

The watchlist task screens against U.S. government sanctions lists, including the Office of Foreign Assets Control (OFAC) SDN list and the Consolidated Sanctions List. It checks both the submitted business name(s) and any individuals submitted via persons_to_screen in a single pass, returning one aggregate result.

The watchlist task will return one of the following results:

Status	Result	Reason
Success	`watchlist_no_hits`	No hits were identified for the business or any screened individuals
Failure	`watchlist_hits`	`X` hit(s) were identified on the consolidated sanctions list (including OFAC)

Where X is the total number of hits across all screened names (business and individuals combined).

note

A watchlist_hits result requires manual review — do not use it as an automatic decline without investigating the specific hits. Common false positives occur when a business or person shares a name with a sanctioned entity but is a different individual or organization.