Incode WebSDK Reference

This page documents the JavaScript API of the Incode Web SDK. The SDK is initialized by calling create, which returns an incode instance that exposes all SDK methods.

create

Initializes the SDK and returns an incode instance. Call this before any other SDK methods.

const onBoarding = OnBoarding.create({
  apiURL: "YOUR_API_URL",
  lang: "en",
});

Parameters:

Returns: The SDK instance (incode object).

initialize

Required beginning with version 1.83.0.

Ensures proper loading of the Web SDK, including the correct translation loading order. Call this after create.

const Onboarding = await create({
  apiURL: apiURL,
  translations: en,
});

await Onboarding.initialize();

isDesktop

Returns true if the user is on a desktop or laptop. Returns false if they are using a mobile device. Use this to conditionally render desktop or mobile flows.

if (onBoarding.isDesktop()) {
  onBoarding.renderRedirectToMobile(containerRef.current, { ... });
} else {
  renderFrontId();
}

renderRedirectToMobile

Renders the Redirect to Mobile component. This prompts desktop users to continue on their mobile phone.

onBoarding.renderRedirectToMobile(containerRef.current, {
  session: session,
  flowId: flowId,
  onSuccess: () => renderFinishScreen(),
});

Options:

renderCombinedConsent

Renders a combined consent interface configured in Dashboard.

renderCombinedConsent(consentElement, {
  token: session,
  onSuccess: () => console.log("Consent given"),
  consentId: "someConsentId",
});

Parameters:

sendGeolocation

Requests the user's coordinates and sends them to the session.

onBoarding.sendGeolocation({ token }).then((res) => res);

Parameters:

Returns: { "location": "City, Country" }

sendFingerprint

Sends device and browser information for the session. This includes browser version, device model, OS, SDK version, and IP address.

onBoarding.sendFingerprint({ token: session.token }).then((response) => {
  console.log(response.success);
});

Parameters:

Returns: { success: boolean, sessionStatus: string }

renderCaptureId

Introduced in version 1.80.0.

Initializes and renders the ID Capture module. This includes the document type selector, capture tutorials, and capture UI for both double-sided and single-sided documents, such as driver's licenses and passports. renderCaptureId captures both sides of double-sided documents in a single call.

Most module options—such as capture attempts, manual capture timeout, and tutorials—are configured in Dashboard, not in code.

const { close } = renderCaptureId(myElement, {
  session: { token: 'YOUR_TOKEN' },
  onSuccess: () => console.log('ID capture successful'),
  onError: (error) => console.error('ID capture failed:', error),
});

Props:

Returns: { close: function }. Call close() to unmount the component.

Error codes (IdError.code):

renderWallet

Launches the Digital ID wallet flow from a custom UI. Use renderWallet when you are building your own UI and want to expose only the digital ID wallet functionality, without the built-in ID chooser screen.

Digital IDs must be enabled for the flow in the Dashboard before calling renderWallet. renderWallet must be called from a user gesture, such as a button click, because Apple Wallet and the browser Digital Credentials APIs require user activation to present the native wallet sheet.

import { renderWallet } from '@incodetech/welcome';

async function onDigitalIdButtonClick(session) {
  await renderWallet({
    session,
    onSuccess: (result) => console.log('Digital ID wallet verification submitted', result),
    onError: (error) => console.error('Digital ID wallet verification failed', error),
  });
}

Props:

Forcing a provider:

await renderWallet({
  session,
  provider: 'google', // or 'apple_web'
  onSuccess: (result) => console.log(result),
  onError: (error) => console.error(error),
});

Success shape (DigitalIdWalletResult):

onSuccess receives the submission decision or status returned by Incode after the encrypted wallet response is submitted.

type DigitalIdWalletResult = {
  success: boolean;
  decision?: string;
  [key: string]: unknown;
} | null;

The wallet call does not return identity attributes directly. To retrieve verified attributes such as name, date of birth, document number, portrait, or issuing jurisdiction, use the standard Incode session result APIs after the wallet verification is processed.

Error codes (DigitalIdWalletError.code):

Hide the built-in Digital ID button in renderCaptureId

If you use the built-in ID chooser (via renderCaptureId) but want to launch Digital ID wallet verification from your own UI, pass hideDigitalIdButton: true in the ID capture configuration. This hides the built-in wallet option in the chooser while keeping Digital IDs enabled in the flow.

import { renderCaptureId } from '@incodetech/welcome';

renderCaptureId(document.getElementById('incode-id-capture'), {
  session,
  captureConfig: {
    // ... other capture options
    hideDigitalIdButton: true,
  },
  onSuccess: (result) => console.log(result),
  onError: (error) => console.error(error),
});

This setting does not disable the Digital ID configuration on the flow, and it does not prevent you from calling renderWallet from your own UI.

renderCaptureFace

Introduced in version 1.81.0.

Initializes and renders the Face Capture module.

const { close } = renderCaptureFace(container, {
  session: { token: 'YOUR_TOKEN' },
  onSuccess: (response) => console.log('Face capture successful', response),
  onError: (error) => console.error('Face capture failed:', error.message),
});

Props:

Returns: { close: function }. Call close() to unmount the component.

Error codes (FaceError.code):

renderDocumentSelector

Renders a Document Selector in a given container. Accepts the same parameters as renderCamera, excluding type.

renderDocumentSelector(element, {
  onSuccess: () => { /* success handler */ },
  onError: () => { /* error handler */ },
});

Key Options:

renderCamera

For new integrations, use renderCaptureId and renderCaptureFace instead.

Enables the device camera to capture an ID, selfie, or proof of address document.

incode.renderCamera("front", container, {
  onSuccess: myCallback,
  onError: console.log,
  numberOfTries: 3,
  token: session.token,
});

Type Values (Capture Modes):

Key Options:

Returns: { close: function }. Call close() to unmount the component.

processId

Processes the uploaded ID document. Runs Incode's validations, tests, and OCR parsing. Call this after both the front and back uploads are complete. After calling this, the user cannot upload the ID again.

const response = await onBoarding.processId({ token });

Returns: { success: true }

processFace

Processes the selfie after the user uploads both their selfie and the front of their ID.

const response = await onBoarding.processFace({ token });

Returns:

renderVideoSelfie

Renders the Video Selfie module. The user takes a selfie, shows their ID, answers questions, and confirms acceptance.

Note: Localization is not supported for the Video Selfie module. You must set a fixed language during session creation using {"language": "en-US"}.

onBoarding.renderVideoSelfie(
  container,
  {
    token: session,
    showTutorial: true,
    modules: ["front", "back", "speech", "selfie"],
    speechToTextCheck: true,
  },
  {
    onSuccess: () => alert("speech detected"),
    onError: () => alert("speech not detected"),
    numberOfTries: 3,
  }
);

Options:

renderConference

Renders the Video Conference module.

onBoarding.renderConference(
  container,
  { token: token, showOTP: false },
  {
    onSuccess: (status) => {
      // status: 'close', 'deny', or 'approve'
    },
  }
);

Options:

Callbacks: onSuccess(status), onError, onConnect, onLog

renderAuthFace

Available from SDK version 1.84.0. Replaces the deprecated renderLogin.

Renders the Face Authentication UI. Supports 1:1 and 1:N authentication modes.

IncodeSDK.renderAuthFace(container, {
  session: session,
  authHint: 'customer-uuid-12345', // omit for 1:N
  onSuccess: mySuccessCallbackFn,
  onError: myErrorCallbackFn,
});

Options:

renderLogin

Deprecated. Use renderAuthFace instead.

renderEnterCurp

Renders the CURP entry and validation component (Mexico only).

incode.renderEnterCurp(document.getElementById('app'), {
  token: session.token,
  onSuccess: console.log,
  onError: console.log,
});

renderSignature

Renders the Signature component for digital signature capture.

onBoarding.renderSignature(document.getElementById("app"), {
  token: session.token,
  onSuccess: console.log,
  onError: console.log,
});

Options:

addPhone

Adds a phone number to the current session. Throws an error if a customer with that phone number already exists.

onBoarding.addPhone({ token, phone }).then((res) => res);

Returns: { success: true }

addCustomFields

Adds custom fields to the current onboarding session.

incode.addCustomFields({
  token: session.token,
  fields: { watchlistName: name },
});

Returns: { success: true }

renderBiometricConsent

Renders the biometric consent screen. Should be shown as the first screen if createSession returns showMandatoryConsent: true.

incode.renderBiometricConsent(document.getElementById("app"), {
  token: session,
  onSuccess: console.log,
  onCancel: console.log,
  regulationType: "US_Illinois",
});

Options:

renderMlConsent

Renders the ML Consent component.

onBoarding.renderMlConsent(document.getElementById("app"), {
  token: session,
  type: "Worldwide",
  onSuccess() { console.log("ML accepted"); },
});

renderQr

Renders a QR code that, when scanned, opens a specified URL or web flow on mobile.

onBoarding.renderQr(containerRef.current, {
  session: session,
  flowId: flowId,
  onSuccess: () => showFinishScreen(),
});

Options:

renderQrScanner

Renders a universal QR code scanner. Stores the QR value in the session as the qrCodeText custom field.

onBoarding.renderQrScanner(document.getElementById("app"), {
  session: session,
  onSuccess() { console.log("QR scanned"); },
});

renderUserConsent

Deprecated. Use renderCombinedConsent instead.

renderFiscalQr

Renders a QR scanner to retrieve information from the URL in the QR code. Mexico only.

onBoarding.renderFiscalQr(document.getElementById("app"), {
  session: session,
  onSuccess() { console.log("Fiscal QR scanned"); },
});