- Docs
- API reference
- Endpoints and schemas
- KYB API
- Checks
Verification tier
A graded measure of how independently a business's existence can be corroborated.
The verification tier Beta grades the third-party evidence that the matched registered entity is real and operating. Unlike the other checks, it does not compare your input with Enigma’s records. It reports how hard that evidence would be to fabricate, and lists the signals behind the grade.
The verification tier is part of the verify package, so a Verify a business request returns it with no extra parameter. It appears as the verification_tier task in risk_summary.tasks, and nowhere else in the response. How checks work shows it beside the other tasks; this page defines its results and the signals behind them.
Here is a verification_tier task, trimmed from the full example.
{ "task_name": "verification_tier", "status": "success", "result": "tier_1", "reason": "Tier 1 (Low): verification is supported by trust-based records such as corporate registration and EIN. These are self-reported and the accuracy of the information is neither validated nor corroborated by independent sources.", "criteria": { "met": ["has_active_registration", "has_ein"], "not_met": [ "has_reviews", "has_web_presence", "has_card_transactions", "has_substantial_review_history", "has_open_location", "has_government_record" ], "evidence": { "active_registration_count": 2, "review_count": 0, "website_count": 1, "total_review_count": 0, "open_location_count": 0 } }}When it runs
Section titled “When it runs”You do not request the verification tier. It runs on every verify request with top_n=1, which is also what a request that sets none of package, products or top_n gets.
| Request | verification_tier task |
|---|---|
package=verify, top_n=1 |
Present. |
package=identify |
Absent. |
top_n greater than 1 |
Absent. No task runs, so the response has no risk_summary. |
Attribute-only request (products) |
Absent. The verification tier is part of the verify package only; a products request runs only the add-on tasks it lists, such as watchlist or tin_verification. |
verification_tier in attrs on identify |
Ignored. No task is added and no error is returned. |
verification_tier in products |
400 with the message Unknown attribute(s) in 'products': ... |
| Person-only screen | Present when the package is verify or omitted, with the result tier_unknown. |
The task object
Section titled “The task object”The verification_tier task has the same task_name, status, result and reason fields as every task. It has criteria in place of sources.
task_nameAlways
verification_tier.statusAlways
success, including when no verification tier is available. Do not branch on it.resultThe verification tier. See Verification tiers. Branch on this field.
reasonA readable description of the result. The wording can change: display it, never match on it.
criteriaThe signals behind the result. See The criteria object.
Verification tiers
Section titled “Verification tiers”A higher verification tier means the evidence is harder to fabricate. It does not mean the business is larger, older, more profitable or lower risk.
| Result | Status | Meaning |
|---|---|---|
tier_1 | success | Low corroboration. Only self-reported records support the business, such as a corporate registration or an EIN. |
tier_2 | success | Medium corroboration. At least one independent third-party signal supports the business, such as an established web presence or customer reviews. |
tier_3 | success | High corroboration. Several hard-to-fabricate third-party signals support the business, such as card transaction activity, government records, verified operating locations or a substantial review history. |
tier_unknown | success | No verification tier is available, including when no business matched. criteria is empty. This is an absence of data, not a low grade. |
The result is tier_unknown when:
- No registered entity matched, including on a person-only screen.
- Enigma holds no verification tier for the matched registered entity.
If you receive tier_unknown for businesses you expect to be well documented, contact Enigma to confirm the verification tier is enabled for your account.
While the verification tier is in beta, result can carry a value not listed here. Handle any value you do not recognize the same way as tier_unknown.
The criteria object
Section titled “The criteria object”criteria lists every signal behind the result, not grouped by verification tier, so read the signals as a whole. For example, a tier_3 result can list has_ein in not_met.
metYes-or-no signals observed for the business.
not_metYes-or-no signals that were not observed.
evidenceCounts and dates behind the signals, keyed by name. See Evidence.
When result is tier_unknown, criteria is {"met": [], "not_met": [], "evidence": {}}.
A yes-or-no signal whose value is unknown appears in evidence with the value null, and in neither met nor not_met. So a signal missing from not_met has not necessarily been met.
When you read criteria:
- Test
metandnot_metfor membership. Do not rely on item order. - Read
evidenceby key, and allow for a missing key. - Ignore signal names you do not recognize. The set can grow.
Signals
Section titled “Signals”These yes-or-no signals appear in met, in not_met, or as null in evidence.
Show the 8 values
| Signal | Supports | Indicates |
|---|---|---|
has_active_registration |
tier_1 |
An active corporate registration is on file. |
has_ein |
tier_1 |
An EIN is on file for the business. |
has_web_presence |
tier_2 |
The business has an established web presence. |
has_reviews |
tier_2 |
The business has customer reviews. |
has_card_transactions |
tier_3 |
Card transaction activity is observed for the business. |
has_substantial_review_history |
tier_3 |
The business’s reviews span a substantial period. |
has_open_location |
tier_3 |
The business has a verified open operating location. |
has_government_record |
tier_3 |
The business appears in government records beyond its registration. |
Evidence
Section titled “Evidence”These values appear in evidence. Enigma passes them through as it holds them, so any value can be null. Read counts and dates defensively.
| Key | Type | Signal | Description |
|---|---|---|---|
active_registration_count |
integer |
has_active_registration |
The number of active registrations found. |
review_count |
integer |
has_reviews |
The number of reviews found. |
website_count |
integer |
has_web_presence |
The number of websites associated with the business. |
total_review_count |
integer |
has_substantial_review_history |
The total number of reviews across all review sources. |
open_location_count |
integer |
has_open_location |
The number of verified open operating locations. |
earliest_review_date |
string |
None | The date of the earliest observed review, as a YYYY-MM-DD string, when available. |
A count and its signal are reported separately. A count does not by itself mean the signal is met.
Example
Section titled “Example”A verify request needs nothing extra to return the verification tier. The request below sets package=verify and top_n=1 for clarity. Both are the defaults.
curl --request POST "https://api.enigma.com/v2/kyb/?package=verify&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" } }'Both example responses are trimmed to the verification_tier task.
A registered entity supported only by active registrations and an EIN on file.
{ "response_id": "2a1b3c4d-5e6f-7890-abcd-ef1234567890", "risk_summary": { "tasks": [ { "task_name": "verification_tier", "status": "success", "result": "tier_1", "reason": "Tier 1 (Low): verification is supported by trust-based records such as corporate registration and EIN. These are self-reported and the accuracy of the information is neither validated nor corroborated by independent sources.", "criteria": { "met": ["has_active_registration", "has_ein"], "not_met": [ "has_reviews", "has_web_presence", "has_card_transactions", "has_substantial_review_history", "has_open_location", "has_government_record" ], "evidence": { "active_registration_count": 2, "review_count": 0, "website_count": 1, "total_review_count": 0, "open_location_count": 0 } } } ] }}No verification tier is available, so criteria is empty.
{ "response_id": "2a1b3c4d-5e6f-7890-abcd-ef1234567890", "risk_summary": { "tasks": [ { "task_name": "verification_tier", "status": "success", "result": "tier_unknown", "reason": "No verification tier was returned for this business.", "criteria": { "met": [], "not_met": [], "evidence": {} } } ] }}Read the verification tier
Section titled “Read the verification tier”The verification tier describes the matched registered entity. It does not show that the business you submitted is that entity. The name, address and person tasks check that.
result gives the grade, and criteria lists the signals behind it: met and not_met name the signals that were and were not observed, and evidence holds the counts and dates behind them. When result is tier_unknown, criteria is empty.
tier_unknown means no grade is available. It is an absence of data, not a low grade.
Related
Section titled “Related”- How checks work: every task and its results.
- Verify a business: the request that returns the verification tier.
- Packages: what
verifyincludes. - Response object: where
risk_summarysits in a complete response. - Registered entities: the matched registered entity the verification tier describes.