---
title: "eKYC Pre-fill Module"
url: "https://developer.incode.com/sdk-reference/web-sdk-2-module-ekyc-prefill/"
section: "sdk-reference"
group: "Incode Web SDK 2 Reference / Web SDK 2 Individual Modules"
version: "v1.1"
status: "live"
---
# eKYC Prefill Module

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

The eKYC Prefill module (`EKYC_PREFILL`) asks for the few inputs that Incode needs to look a person up, then posts them and moves on. It collects only the lookup inputs. You review the result in Dashboard.

Which inputs show and which are required come from the module configuration that your Flow or Workflow serves. The module needs an onboarding session whose Flow or Workflow includes `EKYC_PREFILL`.

This module follows a [form-based pattern](/sdk-reference/web-sdk-2-module-patterns/#1-form-based-modules) variant: a small, configuration-driven form with no pre-fill from earlier modules.

## Data sources

| Source | Country | Inputs the form can ask for |
| --- | --- | --- |
| `US_PREFILL` | United States | Phone, date of birth, SSN, last name. Typically the phone is required, plus at least one of date of birth, SSN or last name. Your configuration decides. |
| `US_PREFILL_EXPRESS` | United States | Phone. |
| `BR_PREFILL` | Brazil | CPF. |

The configuration decides which of these inputs render and which are required. An input the configuration doesn't enable doesn't show.

## Tag

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

## Properties

| Property   | Type                                          | Required | Description                                           |
| ---------- | --------------------------------------------- | -------- | ----------------------------------------------------- |
| `config`   | `EkycPrefillModuleConfig \| EkycPrefillConfig` | ❌       | Module configuration. A Flow or Workflow supplies it. |
| `manager`  | `EkycPrefillManager`                          | ❌       | A manager you created, to drive the module yourself.  |
| `onFinish` | `() => void`                                  | ❌       | Called when the module finishes. |
| `onError`  | `(error: string) => void`                     | ❌       | Called when the session expires. Retryable errors stay in the module's `error` state. |

## Configuration

`EkycPrefillModuleConfig` is the shape the onboarding flow serves. It is exported from `@incodetech/core/ekyc-prefill`.

```typescript
type EkycPrefillModuleConfig = {
  country?: string | null;
  source?: string | null;
  fields?: EkycPrefillServedField[] | null;
  requireAnyOf?: string[] | null;
  autoExecution?: boolean | null;
};

type EkycPrefillServedField = {
  field: string;
  check?: boolean | null;
  mandatory?: boolean | null;
};
```

| Option | Description |
| --- | --- |
| `country` | Country of the source, `US` or `BR`. Selects the form. |
| `source` | The data source, such as `US_PREFILL`. Sent with the lookup. |
| `fields` | The inputs. A field renders only when `check` is `true`, and is required only when `mandatory` is `true`. The field names are `phone`, `dateOfBirth`, `ssn`, `surName` (last name) and `taxIdNumber` (CPF). |
| `requireAnyOf` | Rendered inputs of which the user must fill at least one. The form shows a hint under them, and an error when the user leaves them empty. |
| `autoExecution` | When `true`, the backend runs the lookup itself, so the module finishes without showing a screen. |

The module can't render a configuration with no `fields`, a missing `country` or `source`, or a `mandatory` field it doesn't know. It then reports `misconfigured`.

You don't normally set this configuration yourself. `toEkycPrefillConfig(config)` normalizes a served configuration into the `EkycPrefillConfig` the manager takes.

## Input behavior

- **Phone**: the user picks a country code and enters the number. The module sends it in international format.
- **Date of birth**: it can't be in the future or more than 120 years ago.
- **SSN**: shown masked, with a show/hide toggle, and typed as `XXX-XX-XXXX`.
- **CPF**: typed as `XXX.XXX.XXX-XX`; 11 digits are also accepted. An invalid CPF shows an error under the field.
- **Last name**: the field keeps characters a name can hold and drops the rest.

If the backend rejects the phone, the error shows under the phone field. Other rejections show a message above the form.

## State machine

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

| Status         | Description                                                                                               |
| -------------- | --------------------------------------------------------------------------------------------------------- |
| `idle`         | Initial state. Call `load()`.                                                                             |
| `form`         | Rendering the lookup inputs.                                                                              |
| `submitting`   | Posting the lookup.                                                                                       |
| `error`        | The lookup could not run. `errorKind` is `'busy'` when another lookup for the session is running, else `'unavailable'`. |
| `limitReached` | The session's lookup limit is reached. Call `continue()` to move on.                                      |
| `misconfigured`| The configuration can't be rendered, or the session's flow doesn't allow the lookup.                      |
| `finished`     | Terminal. Also reached right after `load()` with `autoExecution: true`.                                    |
| `closed`       | The user dismissed the module.                                                                            |

### Form-state properties

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

| Property | Type | Description |
| --- | --- | --- |
| `country` | `string` | Country the form renders for. |
| `fields` | `EkycPrefillFieldDef[]` | Ordered field descriptors for rendering. |
| `values` | `Record<string, string \| undefined>` | Current values. |
| `errors` | `EkycPrefillFieldErrors` | Field-name map of `{ key: string, params?: Record<string, string \| number> }`; translate each key with its parameters. |
| `anyOf` | `EkycPrefillAnyOfState \| undefined` | The "at least one of" rule: `fields`, a `message` key and `showError`. Show the message as an error when `showError` is `true`, otherwise as a hint. |
| `submitError` | `string \| undefined` | Message key for a rejection that no single field explains. |
| `canSubmit` | `boolean` | Whether every rule passes, so the lookup can be submitted. |

Use `EkycPrefillState` from `@incodetech/core/ekyc-prefill` for the complete union. In `error`, read `state.errorMessage` (`string | undefined`) and provide a translated fallback.

## API methods

| Method | Purpose | Callable when |
| --- | --- | --- |
| `load()` | Build the form from the configuration, or finish at once with `autoExecution`. | `idle` |
| `setField(name, value, isValid?)` | Set one input and clear its error. Pass `isValid: false` when the input knows the value is malformed, as a phone input does. | `form` |
| `validateField(name)` | Validate one input. Call it on blur. | `form` |
| `submit()` | Validate the form and, when it passes, post the lookup. | `form` |
| `retry()` | Repeat a lookup that could not run. | `error` |
| `continue()` | Move on after the lookup limit is reached. | `limitReached` |
| `close()` | Close the module. | `form`, `error`, `limitReached`, `misconfigured` |

```typescript
import { createEkycPrefillManager } from '@incodetech/core/ekyc-prefill';

const manager = createEkycPrefillManager({ config: moduleConfiguration });
manager.subscribe((state) => {
  if (state.status === 'form') render(state.fields, state.values, state.errors);
});
manager.load();
manager.setField('phone', '+12025550123');
manager.submit();
```

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

## See also

- [Module: eKYC](/sdk-reference/web-sdk-2-module-ekyc/): collects the data for a full identity check
- [Module: Phone](/sdk-reference/web-sdk-2-module-phone/): the phone number whose value the backend can use when `autoExecution` is on
- [Module Patterns → form-based](/sdk-reference/web-sdk-2-module-patterns/#1-form-based-modules)
- [Individual Modules](/sdk-reference/web-sdk-2-individual-modules/)