---
title: "eKYC Module"
url: "https://developer.incode.com/sdk-reference/web-sdk-2-module-ekyc/"
section: "sdk-reference"
group: "Incode Web SDK 2 Reference / Web SDK 2 Individual Modules"
version: "v1.1"
status: "live"
---
# eKYC 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 eKYC (electronic Know Your Customer) module collects identity verification data through a configurable form including name, address, phone, email, SSN/tax ID, date of birth, ID numbers, etc. and submits it to Incode's KYC verification engine. The displayed fields and their data sources (manual entry, document OCR, prior phone/email modules) are dashboard-driven.

> Follows a [form-based pattern](/sdk-reference/web-sdk-2-module-patterns/#1-form-based-modules) variant — dashboard-driven dynamic field schema with optional pre-fill from earlier modules. See the patterns page for the shared lifecycle.

## Tag

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

## Properties

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

## Configuration

```typescript
type EkycConfig = {
  flowId?: string;
  verificationFields?: EkycVerificationFields;
  source?: string;
  fieldsCountry?: string;
  enablePhoneRisk?: boolean;
};
```

| Option               | Type                     | Required | Description                                                                                                                                              |
| -------------------- | ------------------------ | -------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `flowId`             | `string`                 | ❌       | Session flow ID; injected by the orchestrator.                                                                                                           |
| `verificationFields` | `EkycVerificationFields` | ❌       | Per-field source map. Each value is `'user_input' \| 'document_scan' \| 'poa_document' \| 'phone_module_input' \| 'email_module_input' \| false` (omit). |
| `source`             | `string`                 | ❌       | Backend-side override for default field source.                                                                                                          |
| `fieldsCountry`      | `string`                 | ❌       | ISO country code; controls country-specific field rendering.                                                                                             |
| `enablePhoneRisk`    | `boolean`                | ❌       | Enable phone-risk subprocess on submit.                                                                                                                  |

The full list of `EkycVerificationFields` keys: `name`, `address`, `phone`, `email`, `SSN`, `taxId`, `nationality`, `'date of birth'`, `dlNumber`, `dlState`, `dlExpireAt`, `last4SSN`, `idNum`, `idNum1`, `gender`, `panNumber`. Each field can be sourced from manual entry, OCR'd ID data, POA document data, or a prior phone/email module.

### Dashboard field configuration

`EkycConfig` above is what you set in application code. The dashboard sends its own shape, `EkycModuleConfig`, which the orchestrator resolves into the rendered form. You do not set it yourself, but it is exported from `@incodetech/core/ekyc` so you can type a response you inspect.

It configures each verifiable field with a **pair** of properties:

- `check<Field>` (`boolean`): whether to verify that field at all.
- `<field>Source` (`string`): where its value comes from, using the same source names as `verificationFields`.

For example, `checkName` plus `nameSource`, and `checkDob` plus `dobSource`. The pairs cover `Name`, `Email`, `Address`, `Phone`, `Ssn`, `Dob`, `Nationality`, `DlNumber`, `DlState`, `DlExpireAt`, `Last4SSN`, `IdNum`, `IdNum1`, `Gender`, and `PanNumber`. A top-level `source` sets the default for fields with no explicit source, and `riskAddons` and `enablePhoneRisk` carry the risk configuration.

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

## Risk addons

The dashboard-driven module config exposes a `riskAddons` array (`RiskAddon`: `'phoneCheck' | 'advancedPhoneCheck' | 'emailCheck'`). A matching addon renders the corresponding input even when its `checkPhone` / `checkEmail` flag is off:

- `phoneCheck` or `advancedPhoneCheck` renders the phone input.
- `emailCheck` renders the email input.

A module `source` of `RISK_ADDONS_ONLY` runs the eKYC form purely to collect the inputs the configured risk addons need, without a full identity-data check. These values come from the dashboard flow configuration, so most callers pass them through unmodified.

## State machine

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

| Status          | Description                                                                |
| --------------- | -------------------------------------------------------------------------- |
| `loading`       | Fetching field schema and any pre-fill data from prior modules.            |
| `form`          | Rendering the configured form fields; user enters / corrects data.         |
| `submitting`    | Submitting to the eKYC backend.                                            |
| `success`       | Submission accepted.                                                       |
| `finished`      | Terminal.                                                                  |
| `closed`        | User dismissed.                                                            |
| `error`         | Submission or load error.                                                  |
| `misconfigured` | The backend returned no usable field configuration; can't render the form. |

## API methods

Fields come from the dashboard schema, so this module uses one keyed setter rather than a setter per field.

| Method                      | Purpose                                                                       | Callable when |
| --------------------------- | ----------------------------------------------------------------------------- | ------------- |
| `load()`                    | Fetch the field schema and any prefill from earlier modules.                  | `loading`     |
| `setField(name, value)`     | Set one 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`        |
| `submit()`                  | Submit the form.                                                              | `form`        |
| `retry()`                   | Return to the form after a submission error.                                  | `error`       |
| `skip()`                    | Skip verification and continue the flow past the failure.                     | `error`       |

## See also

- [Module: eKYB](/sdk-reference/web-sdk-2-module-ekyb/): equivalent for businesses
- [Module Patterns → form-based](/sdk-reference/web-sdk-2-module-patterns/#1-form-based-modules)
- [Module Patterns → composite](/sdk-reference/web-sdk-2-module-patterns/#5-composite--orchestrator-modules)
- [Individual Modules](/sdk-reference/web-sdk-2-individual-modules/)