Business Verification Warnings & KYB Error Codes

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_REGISTRY_DATA_MISMATCH_WITH_EXPECTED`	The registration number of the company resolved from the registry does not match the `expected_details.registration_number` you sent when creating the session.
`KYB_REGISTRY_DATA_PARTIAL_MATCH_WITH_EXPECTED`	The registration number resolved from the registry only partially overlaps with the expected one, for example a branch or subsidiary suffix.
`KYB_COMPANY_VAT_INVALID`	The official tax registry has no active registration for the company’s VAT number or tax ID, or the VAT number fails its country’s format and check-digit rules. The configured `kyb_vat_invalid_action` is applied (default: In Review).
`KYB_COMPANY_VAT_COULD_NOT_VALIDATE`	The VAT number or tax ID could not be validated because the official registry was temporarily unavailable. The configured `kyb_vat_unverified_action` is applied (default: no effect).
`KYB_COMPANY_VAT_NAME_MISMATCH`	The name registered with the official registry for this number differs from the submitted company name. Informational - includes `registry_name`, `registry_source` and `submitted_name` in `additional_data`, plus `vies_name` when the registry is VIES.

VAT warnings apply wherever the company’s VAT number or tax ID can be validated - see VAT and tax ID validation for the countries and sources.

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_DOCUMENT_UNPROVEN_TEXT_REPLACEMENT`	A text field of the corporate document was blanked and re-typed in another font, and the file holds no proof of whether its content changed. A file that could not be checked in full raises it too, with `additional_data.detection_method` set to `analysis_incomplete`, because the part not checked could hold such a field. Governed by `kyb_document_unproven_text_replacement_action` (default Review; a workflow that never reviews uses its own `kyb_document_tampering_action` when that is Decline, otherwise No action).
`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. A text field blanked and re-typed in another font raises KYB_DOCUMENT_UNPROVEN_TEXT_REPLACEMENT with the same manipulated_regions shape, never KYB_DOCUMENT_SUSPECTED_MANIPULATION on its own: online editors re-type untouched text too, so this warning does not say the content changed. If another signal raises KYB_DOCUMENT_SUSPECTED_MANIPULATION on the same document, the stricter of the two actions decides. 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.
`KYB_KEY_PEOPLE_MISMATCH_WITH_DOCUMENTS`	The directors or shareholders declared on the Key People screen do not match the people named in the uploaded corporate documents: a person named in the documents was never declared, a name nearly matches, a documented shareholder was declared with no ownership role, or a declared ownership percentage contradicts the documents. The configured `kyb_key_people_document_mismatch_action` is applied (default: In Review).

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

Business Verification Warnings & KYB Error Codes

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