DocumentationAPI Reference
General reference · eKYB Reference

eKYB Prefill API Reference

eKYB Prefill 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 Verification, which compares submitted data against official records, Prefill is a pure data-fetching solution: it returns available business data as-is, without performing fuzzy matching, transformations, or assessments.

Prefill 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.

Info

How it differs from Verification

eKYB Verification takes multiple inputs (business name, address, tax ID, UBOs, directors) and returns a Verified / Approximate Match / Unverified result for each field.

eKYB Prefill takes a minimum input (tax ID + country) and returns raw business data retrieved from the source of truth (business name, entity type, registration status, incorporation date, and contact details) without performing any assessment on that data.

This page documents the request and response semantics shared across all eKYB Prefill sources. For source-specific request formats, response fields, and status values, see the country page for the country you are querying. The full list of country pages is on the eKYB Prefill Coverage page.

Info

API authentication

All endpoints require authentication headers. See the Incode API Documentation for details.

Endpoint

POST /omni/externalVerification/ekyb-prefill

The endpoint retrieves business data from the source of truth for the specified tax ID and country.

See the OpenAPI reference for the endpoint schema. {/* TODO: Confirm the exact OpenAPI reference URL slug for the ekyb-prefill endpoint */}

Request parameters

All four parameters are mandatory for every Prefill request.

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

The country and source parameters are used together to route the request to the correct data source. Both are required for every Prefill request.

Sample 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.

Sample response

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

Info

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. See the country page for the exact response structure for that source.

Error responses

For standard HTTP response codes, see the API Error Response page.

taxId is missing, empty, or in an invalid format for the requested country:

message: BadRequestException: Invalid taxId.

country or source is missing or empty:

message: BadRequestException: Missing required field.

Country-specific error responses may also apply. See the country page for the country-specific error responses returned by that source.

{/* TODO: Confirm with PM — the Mexico Prefill country page returns more detailed error messages (including an internal Java package path in the invalid-country-code error) than the ones shown here. Confirm which set of error messages is authoritative. */}

Behavior and design considerations

What Prefill returns

Prefill 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 Prefill service, within your 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. Your platform should handle this case by allowing the user to fill in data manually, if applicable.

Single Session Dashboard results

Prefill results are available on the Business tab in single Session view.

Was this page helpful?