eKYB Pre-fill

Overview of the eKYB identity verification process, which is used by many countries to protect against business-to-business fraud.

eKYB Pre-fill is a data enrichment solution that retrieves and returns business information from official sources of truth using a minimum set of inputs — typically a tax ID. Unlike standard eKYB, which performs verification by comparing submitted data against official records, eKYB Pre-fill is a pure data fetching solution: it returns available business data as-is, without performing fuzzy matching, transformations, or assessments.

This is designed for use cases where you want to populate business information automatically before presenting it to the user or passing it downstream into your own business logic.

📘
How it differs from eKYB
Standard eKYB takes multiple inputs (business name, address, tax ID, UBOs, directors) and returns a Verified / Approximate Match / Unverified result for each field.
eKYB Pre-fill takes a minimum input (tax ID + country) and returns raw business data retrieved from the source of truth — such as business name, entity type, registration status, incorporation date, and contact details — without performing any assessment on that data.

Integration

Direct API Approach

All module configurations and user data can be forwarded directly in the request for performing a KYB Pre-fill lookup.

📘
API Authentication
All endpoints require authentication headers to be specified as stated in Incode API Documentation.

KYB Pre-fill request

POST /omni/externalVerification/ekyb-prefill

This endpoint retrieves business data from the source of truth for the specified tax ID and country. All fields listed below are mandatory.

Field	Data Type	Description
plugins	String array	Must be `["ekyb-prefill"]`. This value is static and mandatory.
source	String	Identifies the pre-fill data source to route the request. Mandatory. Value is country- and configuration-specific (e.g. `MX_KYB_PREFILL`).
country	String	Two-letter Alpha-2 country code (e.g. `MX`). Mandatory.
taxId	String	Tax identifier for the business. Format requirements vary by country. Mandatory.

Note: The country and source parameters are used together to route the request to the correct data source. Both are required for every eKYB Pre-fill request.

{
    "plugins": ["ekyb-prefill"],
    "source": "MX_KYB_PREFILL",
    "country": "MX",
    "taxId": "ABC12345"
}

Response

The response returns business data as retrieved from the source of truth. Fields are passed through without modification, matching, or scoring. The response structure uses the kyb-prefill key.

📘
API Authentication
All endpoints require authentication headers to be specified as stated in Incode API Documentation.

"kyb-prefill": [
    {
        "tin": "ABC12345",
        "name": "COMPANY NAME ABC",
        "entityType": "Company/Legal Entity",
        "registrationStatus": "Active",
        "taxIdEffectiveDate": "2025-07-17",
        "incorporationDate": "2025-05-29",
        "email": "[email protected]"
    }
]

📘
Available fields vary by country
The fields returned in the kyb-prefill response depend on what information is available from the source of truth for the requested country. Not all fields are available in all countries. Refer to the country-specific eKYB Pre-fill pages for the exact response structure.

KYB Pre-fill error responses

Please refer to error response to see conventional HTTP response codes to indicate the success or failure of an API request.

Custom 400 error if taxId is missing, empty, or in an invalid format for the requested country:

message: BadRequestException: Invalid taxId.

Custom 400 error if country or source is missing or empty:

message: BadRequestException: Missing required field.

Behavior and design considerations

What eKYB Pre-fill returns

eKYB Pre-fill is scoped to fetching and returning data from the source of truth. It does not:

Perform fuzzy matching or name comparison
Return Verified / Approximate Match / Unverified statuses
Accept or process address, UBO, or director inputs for matching

Any editing, updating, or additional data collection from the user — and any subsequent business logic applied to the returned data — should be handled outside the Pre-fill service, within the client's own platform.

Invalid or unavailable tax IDs

Two error scenarios are handled separately:

Tax ID is invalid — The API returns a 400 error with an Invalid taxId message. The request is not forwarded to the source of truth.
Tax ID is valid but no data is returned — The API returns an empty or partial response. The client should handle this case by allowing the user to fill in data manually, if applicable.

Single Session Dashboard Results

eKYB Pre-fill results are available in the Single Session view under the Business tab.