---
title: "eKYB Module"
url: "https://developer.incode.com/sdk-reference/web-sdk-2-module-ekyb/"
section: "sdk-reference"
group: "Incode Web SDK 2 Reference / Web SDK 2 Individual Modules"
version: "v1.1"
status: "live"
---
# eKYB Module

:::note
This guide is specific to Web SDK 2.0. If you are still using 1.x, you can find documentation [here](/sdk-reference/web-sdk-reference).  Contact your Incode Representative for upgrade information and check if you are a candidate for this upgrade. <br /><br />Full rollout to all clients still TBD.
:::

The eKYB (electronic Know Your Business) module collects business verification data including country, business name, address, and tax ID, plus a list of UBOs (Ultimate Beneficial Owners). It then submits the package to Incode's business verification engine.

> Follows a [form-based pattern](/sdk-reference/web-sdk-2-module-patterns/#1-form-based-modules) variant with country-aware field schemas and a UBO repeater. See the patterns page for the shared lifecycle.

## Tag

`<incode-ekyb>` is a standard Web Component. Importing the UI subpath registers the custom element; importing the CSS applies the module's styles.

```ts
import '@incodetech/web/ekyb';
import '@incodetech/web/ekyb/styles.css';
```

## Properties

| Property   | Type                      | Required | Description                          |
| ---------- | ------------------------- | -------- | ------------------------------------ |
| `config`   | `EkybConfig`              | ❌       | eKYB configuration                   |
| `onFinish` | `() => void`              | ❌       | Called when KYB submission completes |
| `onError`  | `(error: string) => void` | ❌       | Called when an error occurs          |

## Configuration

```typescript
type EkybConfig = {
  flowId?: string;
  verificationFields?: string[];
  checkBusinessName?: boolean;
  checkAddress?: boolean;
  checkTaxId?: boolean;
  checkUniqueBeneficialOwner?: boolean;
};
```

| Option                       | Type       | Required | Description                                                  |
| ---------------------------- | ---------- | -------- | ------------------------------------------------------------ |
| `flowId`                     | `string`   | ❌       | Session flow ID; injected by the orchestrator.               |
| `verificationFields`         | `string[]` | ❌       | List of fields to verify (used by the backend's KYB checks). |
| `checkBusinessName`          | `boolean`  | ❌       | Run business-name verification.                              |
| `checkAddress`               | `boolean`  | ❌       | Run address verification.                                    |
| `checkTaxId`                 | `boolean`  | ❌       | Run tax-ID verification.                                     |
| `checkUniqueBeneficialOwner` | `boolean`  | ❌       | Validate that UBOs are unique.                               |

### Dashboard field configuration

`EkybConfig` above is what you set in application code. The dashboard sends its own shape, `FlowModuleConfig['EKYB']`, which the orchestrator resolves into the rendered form. You do not set it yourself.

It pairs each verifiable field with a source, the same way [eKYC](/sdk-reference/web-sdk-2-module-ekyc/#dashboard-field-configuration) does:

- `check<Field>` (`boolean`) — whether to verify that field at all.
- `<field>Source` (`'userInput'`) — where its value comes from.

The pairs cover business name (`checkBusinessName` / `businessNameSource`), tax ID (`checkTaxId` / `taxIdSource`), and unique beneficial owner (`checkUniqueBeneficialOwner` / `uniqueBeneficialOwnerSource`).

**Address breaks the naming pattern.** Its source field is `address`, not `addressSource` — so `checkAddress` pairs with `address`. Reach for the sibling name and you get `undefined`.

To change which fields a flow verifies, edit the eKYB module in your dashboard rather than passing config in code.

## Supported countries

Built-in country support: `BR`, `US`, `GB`, `ES`, `IT`, `FR`, `DE`, `IL`, `MX`, `CN`, `NG`, `CM`, `KE`. Each country drives a different field schema (which fields are shown, which are required) — the manager looks up the schema from `EkybCountry` on `country` change.

## State machine

`EkybState` is a discriminated union over `status`:

| Status       | Description                                              |
| ------------ | -------------------------------------------------------- |
| `loading`    | Fetching business field schema for the selected country. |
| `form`       | Rendering the form (business fields + UBO repeater).     |
| `submitting` | Submitting the package to the eKYB backend.              |
| `success`    | Submission accepted.                                     |
| `finished`   | Terminal.                                                |
| `closed`     | User dismissed.                                          |
| `error`      | Submission or load error.                                |

## API methods

Business fields come from the dashboard schema, so this module uses one keyed setter. It also owns the UBO (ultimate beneficial owner) repeater.

| Method                             | Purpose                                                                       | Callable when |
| ---------------------------------- | ----------------------------------------------------------------------------- | ------------- |
| `load()`                           | Fetch the business field schema for the selected country.                     | `loading`     |
| `setCountry(country)`              | Set the country. Changing it reloads the schema.                              | `form`        |
| `setField(name, value)`            | Set one business field, keyed by its name in the schema.                      | `form`        |
| `validateField(name)`              | Validate one field. Call it on blur.                                          | `form`        |
| `searchAddress(query)`             | Fetch address autocomplete suggestions. Debounce it yourself.                 | `form`        |
| `selectAddress(suggestion)`        | Apply one suggestion from `searchAddress`. A street-level result is required. | `form`        |
| `addUbo()`                         | Append a UBO entry. Caps at eight.                                            | `form`        |
| `removeUbo(index)`                 | Remove the UBO entry at that index.                                           | `form`        |
| `setUboField(index, field, value)` | Set `'name'` or `'surname'` on one UBO entry.                                 | `form`        |
| `submit()`                         | Submit the package.                                                           | `form`        |
| `retry()`                          | Return to the form after a submission error.                                  | `error`       |

## See also

- [Module: eKYC](/sdk-reference/web-sdk-2-module-ekyc/): equivalent for individual identity verification
- [Module: Watchlist for Business](/sdk-reference/web-sdk-2-module-watchlist-for-business/): separate sanctions screening
- [Module Patterns → form-based](/sdk-reference/web-sdk-2-module-patterns/#1-form-based-modules)
- [Individual Modules](/sdk-reference/web-sdk-2-individual-modules/)