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

<Component slug="web-2-x-implementation-warning" />

The [KYB Checks](/features-and-modules/kyb-modules/) module (`EKYB_CHECKS`) runs business verification checks. It asks the user for the business country first, then shows the fields that country needs for the checks that your Flow or Workflow selects, and submits them. You review the check results in Dashboard.

The form is built for each country, so the fields, labels, and rules come from the service and can differ between countries. The module needs an onboarding session whose Flow or Workflow includes `EKYB_CHECKS`.

This module follows a [form-based pattern](/sdk-reference/web-sdk-2-module-patterns/#1-form-based-modules) variant: a form that is served for the chosen country, with no pre-fill from earlier modules. For the form-based eKYB module, see [Module: eKYB](/sdk-reference/web-sdk-2-module-ekyb/).

## How the form works

1. The module loads and shows a country field.
2. When the user picks a country, the module loads that country's form. Only the country field shows while the new form loads.
3. The user fills in the fields and continues. The module validates the form and submits it.
4. On success, the module calls `onFinish` with a `referenceId`.

A field can be a text input, a dropdown, a phone input, or a list where the user adds several entries. Each field shows its own validation messages.

## Tag

`<incode-kyb-checks>` 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/kyb-checks';
import '@incodetech/web/kyb-checks/styles.css';
```

## Properties

| Property   | Type                                      | Required | Description                                                                      |
| ---------- | ----------------------------------------- | -------- | -------------------------------------------------------------------------------- |
| `config`   | `KybChecksConfig`                         | ❌       | Module configuration. A Flow or Workflow supplies it.                            |
| `manager`  | `KybChecksManager`                        | ❌       | A manager you created, to drive the module yourself.                             |
| `onFinish` | `(result?: KybChecksResult) => void`      | ❌       | Called when the module finishes. `result.referenceId` identifies the check run.  |
| `onError`  | `(error?: string) => void`                | ❌       | Called on a terminal error, such as an expired session. Load and submit errors stay in the module's `error` state. |

## Configuration

`KybChecksConfig` is the shape the Flow or Workflow serves. It is exported from `@incodetech/core/kyb-checks`.

```typescript
type KybChecksConfig = {
  modules?: KybCheckModuleKey[];
};

type KybCheckModuleKey =
  | 'identity'
  | 'address'
  | 'statusEntityType'
  | 'personAssociation'
  | 'webPresence'
  | 'websiteAnalysis'
  | 'industryInfo'
  | 'financialIntelligence'
  | 'groupStructure';
```

| Option    | Description                                                                                                                                              |
| --------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `modules` | The checks that the Flow or Workflow selects. The service uses them to decide which fields the form asks for. A selected check that a country cannot run is left out of that country's form. |

You don't normally set this configuration yourself. Select the checks in Dashboard.

## Result

`onFinish` receives a `KybChecksResult`:

```typescript
type KybChecksResult = {
  referenceId?: string;
};
```

The result carries only the reference. The outcome of each check is not returned to the browser; review it in Dashboard or retrieve it from your backend.

## State machine

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

| Status          | Description                                                                                                          |
| --------------- | -------------------------------------------------------------------------------------------------------------------- |
| `loading`       | Loading the first form, the country picker.                                                                          |
| `form`          | Rendering the fields.                                                                                                |
| `submitting`    | Submitting the form.                                                                                                 |
| `error`         | A load or a submit failed. `errorKind` is `'load'` or `'submit'`. `canRetry` says whether `retry()` is offered.      |
| `misconfigured` | KYB is not in the session's flow, the session is closed, or the served form is not one this SDK version supports.    |
| `finished`      | Terminal. `result` holds the `referenceId`.                                                                          |
| `closed`        | The user dismissed the module.                                                                                       |

### Form-state properties

These fields exist only when `status === 'form'`.

| Property      | Type                       | Description                                                                                                       |
| ------------- | -------------------------- | ----------------------------------------------------------------------------------------------------------------- |
| `title`       | `KybText \| undefined`     | Title for the form.                                                                                               |
| `sections`    | `KybChecksSection[]`       | Sections in display order. The first holds the country field. Each section has `id`, an optional `title`, and `fields`. |
| `values`      | `KybFieldValues`           | Current values. A list field holds an array of strings; every other field holds a string.                         |
| `errors`      | `KybFieldErrors`           | Field-name map of `KybText` messages.                                                                             |
| `isRefetching`| `boolean`                  | `true` while the form for a newly chosen country loads.                                                           |
| `canSubmit`   | `boolean`                  | `false` until a country is chosen and its form has loaded, and while a new form loads.                            |

A `KybText` is `{ key, text, params? }`. Translate `key` with your own translations and show `text` when there is none. A `params` value can itself be a `KybText`; translate it before you insert it.

### Errors and retries

After a load error, `retry()` is always offered. After a submit error, `retry()` is offered only when the service rejected the request, because otherwise the checks may already have run and a retry could run them twice. When `canRetry` is `false`, offer `close()` instead. The built-in screen does this for you.

## API methods

| Method                          | Purpose                                                                                                                                     | Callable when       |
| ------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------- | ------------------- |
| `load()`                        | Load the first form, the country picker.                                                                                                    | initial             |
| `setField(name, value, isValid?)` | Set one field and clear its error. Setting the country loads that country's form. Pass `isValid: false` when the input knows the value is malformed, as a phone input does. | `form`              |
| `submit()`                      | Validate the form and, when it passes, run the checks.                                                                                      | `form`              |
| `retry()`                       | Repeat the request that failed.                                                                                                             | `error` with `canRetry` |
| `close()`                       | Close the module.                                                                                                                           | `form`, `error`, `misconfigured` |

```typescript
import { createKybChecksManager } from '@incodetech/core/kyb-checks';

const manager = createKybChecksManager({ config: moduleConfiguration });
manager.subscribe((state) => {
  if (state.status === 'form') render(state.sections, state.values, state.errors);
  if (state.status === 'finished') console.log(state.result?.referenceId);
});
manager.load();
manager.setField('country', 'US'); // loads the US form
manager.submit();
```

Here `moduleConfiguration` is the `EKYB_CHECKS` configuration from your Flow or Workflow. On teardown, unsubscribe and call `stop()`.

## See also

- [Module: eKYB](/sdk-reference/web-sdk-2-module-ekyb/): the form-based business verification module
- [Module: eKYC Prefill](/sdk-reference/web-sdk-2-module-ekyc-prefill/): a similar served, configuration-driven form for individuals
- [Module Patterns → form-based](/sdk-reference/web-sdk-2-module-patterns/#1-form-based-modules)
- [Individual Modules](/sdk-reference/web-sdk-2-individual-modules/)