SDK reference, Incode Web SDK 2 Reference / Web SDK 2 Individual Modules

eKYC Pre-fill Module

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

Was this page helpful?