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();

createSession

Start an onboarding session with the Incode Web SDK. Call this after you initialize the SDK and before you render capture modules or run a flow.

Overview

createSession creates a new verification session on Incode’s backend and returns a Session object. The most important field is session.token: you pass it into every subsequent SDK method (renderCamera, executeFlow, executeWorkflow, and so on).

You must call initialize() before creating a session.

const session = await incode.createSession('ALL', null, {
  configurationId: 'YOUR_FLOW_ID',
});

console.log(session.token); // use this for all later SDK calls

Always pass a string as the first argument (for example 'ALL'). Do not call createSession({ configurationId }) — that object-only shape belongs to createNewSession.

Method signature

incode.createSession(
  externalId?: string,
  options?: CreateSessionOptions,
): Promise<Session>

Parameters

Positional arguments

Options object

Session response

createSession resolves to a Session object. Fields you typically use:

Capture timeouts, retry limits, and face-check flags may also be present depending on your flow configuration. Keep the full session object if your UI needs those values; at minimum, persist session.token for the lifetime of the onboarding.

Using the session

Pass session.token into the module or flow you want to run.

Error handling

On failure, createSession rejects with an error that typically includes:

type CreateSessionError = {
  status: number;
  message: string;
};

Handle failures by checking the status code (for example invalid API key, missing flow ID, or network errors). Do not rely on message alone for branching logic in production.

try {
  const session = await incode.createSession('ALL', null, {
    configurationId: 'YOUR_FLOW_ID',
  });
  // continue onboarding…
} catch (error) {
  console.error('Could not start session', error?.status, error);
  // Show a retry or support message to the user
}

createNewSession (recommended)

For new integrations, prefer createNewSession. It uses a single options object and exposes additional fields.

const session = await incode.createNewSession({
  configurationId: 'YOUR_FLOW_ID',
  externalId: 'user-123',
  language: 'en-US',
});

Both methods create the same kind of session and return the same Session shape. Choose one style and stay consistent in your app.

Extra createNewSession options

Common patterns

Attach your user ID

const session = await incode.createSession('ALL', 'order-98765', {
  configurationId: 'YOUR_FLOW_ID',
  externalCustomerId: 'customer-42',
});

Set language explicitly

const session = await incode.createNewSession({
  configurationId: 'YOUR_FLOW_ID',
  language: 'es-ES',
});

Store the token for later steps

const session = await incode.createNewSession({
  configurationId: 'YOUR_FLOW_ID',
});

// Keep token in app state for the rest of onboarding
setSession(session);

// Later modules reuse the same token
incode.renderCamera('selfie', container, {
  token: session.token,
  onSuccess,
  onError,
});

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):

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"); },
});