Business Verification Warnings

Business Verification surfaces warnings on the feature item that produced them. Each warning carries the standard structured shape used across the platform — feature, risk, log_type, short_description, long_description, optional additional_data, and node_id — so you can route review work to the right operational team.

Overview

KYB sessions emit warnings under three core feature tags that map to dedicated feature arrays in the V3 decision response:

Feature tag	Decision response key	What it covers
`KYB_REGISTRY`	`registry_checks[].warnings[]`	Official company-registry lookups. Active status, country restrictions, derivable ownership, missing officer/UBO records.
`KYB_DOCUMENTS`	`document_verifications[].warnings[]`	Incorporation, ownership, address, and shareholder documents the user uploads. Cross-document consistency, OCR, metadata, manipulation, age, and subtype rules.
`KYB_KEY_PEOPLE`	`key_people_checks[].warnings[]`	Person-level signals on directors, officers, UBOs, or user-submitted parties — including PEP/sanctions findings that propagate from AML and prior-decline reuse.

The same KYB workflow can also include the shared features below — they emit warnings on their own arrays:

Feature tag	Decision response key
`AML`	`aml_screenings[].warnings[]`
`PHONE`	`phone_verifications[].warnings[]`
`EMAIL`	`email_verifications[].warnings[]`
`QUESTIONNAIRE`	`questionnaire_responses` (warnings live on the session log)
`LOCATION`	`ip_analyses[].warnings[]`

KYB Registry warnings

Registry warnings use feature: "KYB_REGISTRY" and appear on registry_checks[].warnings[].

Tag	Description
`KYB_COUNTRY_RESTRICTED`	The company’s country is outside the allowed countries configured for the workflow.
`KYB_OFFICERS_DATA_NOT_FOUND`	Officer data is not available from the registry.
`KYB_OWNERSHIP_DATA_NOT_FOUND`	Ownership data is not available from the registry.
`KYB_BENEFICIAL_OWNERSHIP_NOT_DERIVABLE`	Ultimate beneficial ownership could not be established from the registry data.
`KYB_COMPANY_NOT_ACTIVE`	The company is not active according to the registry.
`KYB_COMPANY_NOT_FROM_REGISTRY`	The company was entered manually and could not be verified against a corporate registry.
`KYB_COMPANY_VAT_INVALID`	The company’s VAT number was checked against the EU VIES service and is not valid. The configured `kyb_vat_invalid_action` is applied (default: In Review).
`KYB_COMPANY_VAT_COULD_NOT_VALIDATE`	The VAT number could not be validated because the EU VIES service (or the member state) was temporarily unavailable. The configured `kyb_vat_unverified_action` is applied (default: no effect).
`KYB_COMPANY_VAT_NAME_MISMATCH`	The trader name registered with VIES for this VAT number differs from the submitted company name. Informational — includes `vies_name` and `submitted_name` in `additional_data`.

VAT warnings only apply to companies in the EU VAT area (EU-27 plus Northern Ireland) — see VAT validation.

KYB Document warnings

Document warnings use feature: "KYB_DOCUMENTS" and appear on document_verifications[].warnings[].

Tag	Description
`KYB_DOCUMENT_MISSING_REQUIRED_FIELD`	A required company field — such as company name or registration number — was not found in the document.
`KYB_DOCUMENT_NAME_MISMATCH`	The company name in the document does not match the registry.
`KYB_DOCUMENT_REG_NUMBER_MISMATCH`	The registration number in the document does not match the registry.
`KYB_DOCUMENT_INCORPORATION_DATE_MISMATCH`	The incorporation date in the document does not match the registry.
`KYB_DOCUMENT_ADDRESS_MISMATCH`	The registered address in the document does not match the registry.
`KYB_CROSS_DOCUMENT_MISMATCH`	Company data differs across uploaded corporate documents.
`KYB_DOCUMENT_METADATA_MISMATCH`	The document signature, metadata, or file structure indicates a possible issue.
`KYB_ASSOCIATED_PARTY_MISMATCH`	Directors or shareholders in the document do not match the registry.
`KYB_DOCUMENT_GRAPHIC_EDITOR`	The document appears to have been processed by graphic editing software.
`KYB_DOCUMENT_SUSPECTED_MANIPULATION`	The system detected signs of possible corporate-document manipulation.
`KYB_ADDITIONAL_DATA_NOT_FOUND`	A document field could not be verified because the corresponding registry data is unavailable.
`KYB_DOCUMENT_EXPIRED`	The corporate document exceeds the configured maximum age.
`KYB_DOCUMENT_UNSUPPORTED_SUBTYPE`	The uploaded document subtype is disabled for the workflow.
`KYB_DOCUMENT_MAX_ATTEMPTS_EXCEEDED`	The maximum number of corporate-document upload attempts was exceeded.

For PDF overlay-text manipulation, KYB_DOCUMENT_SUSPECTED_MANIPULATION can include additional_data.manipulated_regions. These are page-coordinate rectangles that identify the suspected edited areas and match the rectangles returned in document_verifications[].items[].document_metadata.overlay_manipulation.manipulated_regions.

KYB Key People warnings

Key People warnings use feature: "KYB_KEY_PEOPLE" and appear on key_people_checks[].warnings[]. They surface person-level issues on directors, officers, UBOs, and user-submitted parties.

Tag	Description
`KYB_PREVIOUSLY_DECLINED_INDIVIDUAL`	A person associated with the company was previously declined in another business verification for the same application.

PEP / sanctions hits on key people are reported as standard AML hits on the matching aml_screenings[] item, not as a KYB-key-people warning. The Key People check propagates the resulting Declined or In Review status onto each affected party so the overall key-people verdict reflects the AML outcome.

Shared feature warnings

The features below can run inside a KYB workflow. They use the same warning catalog as User Verification — full reference on each feature’s own warnings page.

AML

feature: "AML" on aml_screenings[].warnings[].

Tag	Description
`POSSIBLE_MATCH_FOUND`	The AML screening found a possible match requiring review.
`COULD_NOT_PERFORM_AML_SCREENING`	Didit could not perform the AML screening because required screening data was missing or unavailable.

Phone

feature: "PHONE" on phone_verifications[].warnings[].

Tag	Description
`DISPOSABLE_NUMBER_DETECTED`	The phone number is disposable.
`VERIFICATION_CODE_ATTEMPTS_EXCEEDED`	The maximum number of verification-code attempts was exceeded.
`VOIP_NUMBER_DETECTED`	The phone number is a VoIP number.
`DUPLICATED_PHONE_NUMBER`	The phone number was used in another verification process.
`HIGH_RISK_PHONE_NUMBER`	The phone number is high risk.
`PHONE_NUMBER_IN_BLOCKLIST`	The phone number matches an entry in your blocklist.

Email

feature: "EMAIL" on email_verifications[].warnings[].

Tag	Description
`BREACHED_EMAIL_DETECTED`	The email address appears in known data breaches.
`DISPOSABLE_EMAIL_DETECTED`	The email address is disposable.
`UNDELIVERABLE_EMAIL_DETECTED`	The email address is undeliverable.
`DUPLICATED_EMAIL`	The email address was used in another verification process.
`EMAIL_IN_BLOCKLIST`	The email address matches an entry in your blocklist.
`EMAIL_CODE_ATTEMPTS_EXCEEDED`	The maximum number of email verification-code attempts was exceeded.

Questionnaire

feature: "QUESTIONNAIRE".

Tag	Description
`CUSTOM_STATUS_RULE_TRIGGERED`	A workflow status rule evaluated a questionnaire answer and changed the feature status.

Device & IP Analysis

feature: "LOCATION" on ip_analyses[].warnings[].

Tag	Description
`COUNTRY_FROM_DOCUMENT_DOES_NOT_MATCH_COUNTRY_FROM_IP`	The document country does not match the IP country.
`PRIVATE_NETWORK_DETECTED`	A private network, VPN, proxy, or Tor signal was detected.
`EXPECTED_IP_ADDRESS_MISMATCH`	The IP address does not match the expected IP address provided for the session.
`IP_ADDRESS_IN_BLOCKLIST`	The IP address matches an entry in your blocklist.
`DEVICE_FINGERPRINT_IN_BLOCKLIST`	The device fingerprint matches an entry in your blocklist.
`DUPLICATED_IP_ADDRESS`	The same IP address was used in another verification with different `vendor_data`.
`DUPLICATED_DEVICE_FINGERPRINT`	The same device fingerprint was used in another verification with different `vendor_data`.

Examples

Registry — company not active

{
  "registry_checks": [
    {
      "node_id": "feature_kyb_registry",
      "status": "Declined",
      "warnings": [
        {
          "feature": "KYB_REGISTRY",
          "risk": "KYB_COMPANY_NOT_ACTIVE",
          "log_type": "error",
          "short_description": "Company is not active",
          "long_description": "The company is not active according to the registry.",
          "additional_data": null,
          "node_id": "feature_kyb_registry"
        }
      ]
    }
  ]
}

Documents — suspected overlay manipulation

{
  "document_verifications": [
    {
      "node_id": "feature_kyb_documents",
      "status": "In Review",
      "warnings": [
        {
          "feature": "KYB_DOCUMENTS",
          "risk": "KYB_DOCUMENT_SUSPECTED_MANIPULATION",
          "log_type": "warning",
          "short_description": "Possible document manipulation",
          "long_description": "The system detected signs of possible corporate-document manipulation.",
          "additional_data": {
            "manipulated_regions": [
              { "page": 1, "x": 120, "y": 240, "width": 180, "height": 22, "page_width": 612, "page_height": 792 }
            ]
          },
          "node_id": "feature_kyb_documents"
        }
      ]
    }
  ]
}

Key people — previously declined individual

{
  "key_people_checks": [
    {
      "node_id": "feature_kyb_key_people",
      "status": "In Review",
      "warnings": [
        {
          "feature": "KYB_KEY_PEOPLE",
          "risk": "KYB_PREVIOUSLY_DECLINED_INDIVIDUAL",
          "log_type": "warning",
          "short_description": "Previously declined individual",
          "long_description": "A person associated with the company was previously declined in another business verification for the same application.",
          "additional_data": null,
          "node_id": "feature_kyb_key_people"
        }
      ]
    }
  ]
}

Response schema

See where warnings appear in each KYB feature array.

Statuses

Understand how warning severity maps to verification status.

Documents

Review document groups, OCR, and cross-check behavior.

Key people

Officer, UBO, and submitted-party verification flow.

AML report

Hit-level structure for company and person AML screenings.

Reference data models

Canonical shapes for warnings and feature arrays.

Getting Started

Features

Business Profiles

Reference

Console

Overview

KYB Registry warnings

KYB Document warnings

KYB Key People warnings

Shared feature warnings

AML

Phone

Email

Questionnaire

Device & IP Analysis

Examples

Registry — company not active

Documents — suspected overlay manipulation

Key people — previously declined individual

Response schema

Statuses

Documents

Key people

AML report

Reference data models

​Overview

​KYB Registry warnings

​KYB Document warnings

​KYB Key People warnings

​Shared feature warnings

​AML

​Phone

​Email

​Questionnaire

​Device & IP Analysis

​Examples

​Registry — company not active

​Documents — suspected overlay manipulation

​Key people — previously declined individual

​Related

Response schema

Statuses

Documents

Key people

AML report

Reference data models

Overview

KYB Registry warnings

KYB Document warnings

KYB Key People warnings

Shared feature warnings

AML

Phone

Email

Questionnaire

Device & IP Analysis

Examples

Registry — company not active

Documents — suspected overlay manipulation

Key people — previously declined individual

Related