Warning
This guide is specific to Web SDK 2.x. For Web SDK 1.x, you can find documentation here.
Do not attempt to upgrade or implement without support. Contact your Incode representative to check if you are a candidate for this upgrade.
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 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.
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.
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 |
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: collects the data for a full identity check
- Module: Phone: the phone number whose value the backend can use when
autoExecutionis on - Module Patterns → form-based
- Individual Modules