# eKYB Verification API Reference 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](https://developer.incode.com/docs/ekyb-coverage) page. ### API authentication All endpoints require authentication headers. See the [Incode API Documentation](https://developer.incode.com/reference/introduction) 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](https://developer.incode.com/reference/externalverificationekyb) 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`, and `people`. - Brazil returns a `kybSource.uboNames` array with the full list of UBOs stored in the CNPJ database, correlated to `ubo_name_match` entries via `nameId_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](https://developer.incode.com/reference/introduction#api-responses) 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.