This page documents the request and response semantics shared across all eKYB sources. For source-specific request parameters, response fields, and status values, see the country page for the country you are verifying. The full list of country pages is on the eKYB Coverage page.
Info
API authentication
All endpoints require authentication headers. See the Incode API Documentation for details.
Endpoint
POST /omni/externalVerification/ekyb
The endpoint performs an eKYB check for the business specified. It can be called with an empty body {}, in which case information is pulled from the module configuration and session details. When called with a populated body, the submitted values override any pre-existing configuration and session data.
See the OpenAPI reference for the endpoint schema.
Common request parameters
Most eKYB sources accept a common set of request parameters. Country-specific documentation lists which parameters are required, optional, or unsupported for a given country.
| Parameter | Description |
|---|---|
plugins |
Array. Must be ["ekyb"]. |
businessName |
Name of the business. |
country |
Two-letter Alpha-2 country code identifying the country to verify against. |
taxId |
Tax identifier for the business. Naming, format, and validation rules vary by country. |
street |
Street name of the business. |
houseNo |
Building or house number. |
addressLine2 |
Second line of the business address. |
city |
City in the business address. |
state |
State in the business address. |
postalCode |
Postal code, formatted per country conventions. |
uboNames |
Array of full legal names of Unique Beneficial Owners to check against records associated with the business. |
directors |
Array of full legal names of directors to check against records associated with the business. |
The country parameter limits business validation to the specified country. Only businesses established in the selected country are validated.
Common response fields
Most eKYB sources return a common set of response fields. Which fields appear depends on the country and, in some cases, the verification variant (for example, US Advanced vs US Advanced+). The country page for each country lists the specific fields returned and their status values.
| Key | Description |
|---|---|
name |
Match status for the submitted business name against the government source of truth. |
tin |
Match status for the submitted tax ID against the government source of truth. May include reasonCodes indicating which tax ID type was verified. |
address_verification |
Match status for the submitted address against the government source of truth. |
cityMatch |
Match status for the submitted city. |
postalCodeMatch |
Match status for the submitted postal code. |
registrationStatus |
Registration status of the business in the government source of truth. Values vary by country; see country page for details. |
entityType |
Legal entity type of the business, if available. |
ubo_name_match |
Match status for each submitted UBO name. When multiple UBOs are submitted, one entry appears per name, distinguished by uboName_input. |
directors_name_match |
Match status for each submitted director name. When multiple directors are submitted, one entry appears per name, distinguished by directorsName_input. |
Some sources return additional country-specific fields. For example:
- US Advanced+ returns
address_deliverability,address_property_type, andpeople. - Brazil returns a
kybSource.uboNamesarray with the full list of UBOs stored in the CNPJ database, correlated toubo_name_matchentries vianameId_match.
Refer to the country page for the specific set of fields returned.
Status value conventions
Match status values follow a general pattern across sources, but the exact set of values varies by country and field. Common patterns include:
| Value | Meaning |
|---|---|
Verified |
The submitted value matches the value in the source of truth. |
Approximate Match |
The submitted value is a close match under Incode's fuzzy matching algorithm, but not exact. |
Unverified |
The submitted value does not match, or the source of truth has no data for this field. |
The tax ID (tin) field may use Found / Not Found status values on some sources rather than the match values above. See the country page for the exact status values returned per source.
Approximate Match
Approximate Match is generated through Incode's proprietary fuzzy matching algorithm. When returned, the algorithm has identified a close but not exact match between the submitted value and the value in the source of truth for a particular field. This value is returned when exact matches are not possible due to misspellings, typographical errors, or minor variations in input data.
Error responses
For standard HTTP response codes for API request success or failure, see the API Error Response page.
Custom 400 error messages are returned when required fields are empty or null. The specific message varies by country and by which field is missing. Common patterns include:
businessName, taxId, and country are minimum required fields(most countries)taxId and country are minimum required fields(some countries, including China)BadRequestException: Invalid taxId(India)Country field is either not correct or available.(India)
Refer to the country page for country-specific error message language.