--- title: "Incode WebSDK Reference" url: "https://developer.incode.com/sdk-reference/web-sdk-reference/" section: "sdk-reference" group: "Web SDK Reference" version: "v1.1" status: "live" --- # 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. ```jsx const onBoarding = OnBoarding.create({ apiURL: "YOUR_API_URL", lang: "en", }); ``` **Parameters:** | Name | Type | Required | Default | Description | | ------------------- | ------- | -------- | ------- | ------------------------------------------------------------------------------ | | `apiKey` | String | No | | API key provided by Incode. | | `apiURL` | String | Yes | | API URL provided by Incode. | | `lang` | String | No | | Language code, such as `en` or `es`. | | `encrypt` | Boolean | No | `false` | Enables encryption. | | `translations` | Object | No | | Custom translations object. Contact Incode support for the required structure. | | `opencvURL` | String | No | | Custom URL for the OpenCV library. | | `facefinderURL` | String | No | | Custom URL for the face finder library. | | `darkMode` | Boolean | No | `false` | Shows dark variants for all tutorials. | | `fingerprintApiKey` | String | No | | Fingerprint API key. | | `useSha256` | Boolean | No | | Enables SHA-256 encryption. | **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`. ```jsx 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. ```js 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`](#createnewsession-recommended). ### Method signature ```ts incode.createSession( externalId?: string, options?: CreateSessionOptions, ): Promise ``` ### Parameters #### Positional arguments | Argument | Type | Required | Description | | ------------ | -------- | -------- | ------------------------------------------------------------------------------------------- | | `externalId` | `string` | No | Your own identifier for this session (for example a user or application ID in your system). | #### Options object | Option | Type | Required | Description | | -------------------- | -------- | ----------- | ----------------------------------------------------------------------------------------------------------- | | `configurationId` | `string` | Recommended | Flow or workflow ID from the Incode dashboard. Required for almost all integrations. | | `externalCustomerId` | `string` | No | Your customer / end-user ID. | | `uuid` | `string` | No | UUID when linking or resuming an identity. | | `interviewId` | `string` | No | Interview ID when continuing an existing interview. | | `customFields` | `object` | No | Custom key/value data stored on the session. | | `language` | `string` | No | Session language (for example `en-US`, `es-ES`, `pt-BR`). If omitted, the SDK uses the current UI language. | | `urlUuid` | `string` | No | UUID used with QR redirect / phishing-resistance flows. | ### Session response `createSession` resolves to a `Session` object. Fields you typically use: | Field | Type | Description | | ---------------------- | --------- | -------------------------------------------------- | | `token` | `string` | Session token. Pass this to all later SDK methods. | | `interviewId` | `string` | Interview identifier for the session. | | `interviewCode` | `string` | Human-readable interview code. | | `clientId` | `string` | Your Incode client ID. | | `existingSession` | `boolean` | `true` if an existing session was reused. | | `showMandatoryConsent` | `boolean` | Whether mandatory consent should be shown. | | `regulationType` | `string` | Regulation context for consent (when available). | 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: ```ts 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. ```js 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`](#create-new-session). It uses a single options object and exposes additional fields. ```js const session = await incode.createNewSession({ configurationId: 'YOUR_FLOW_ID', externalId: 'user-123', language: 'en-US', }); ``` | | `createSession` | `createNewSession` | | -------------- | -------------------------------------- | -------------------------------------------------------------------- | | Call style | `(countryCode, externalId?, options?)` | `{ ...options }` | | First argument | Required string (unused; use `'ALL'`) | Not applicable | | Extra options | — | `loginHint`, `integrationReference`, `disableFingerprint`, `version` | | Recommendation | Existing integrations | New integrations | 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 | Option | Description | | ---------------------- | -------------------------------------------------------------- | | `loginHint` | Optional auth hint for workflow-based sessions. | | `integrationReference` | Reference string for your integration. | | `disableFingerprint` | Set `true` to skip device fingerprinting during session start. | | `version` | Optional version string associated with fingerprinting. | ### Common patterns #### Attach your user ID ```js const session = await incode.createSession('ALL', 'order-98765', { configurationId: 'YOUR_FLOW_ID', externalCustomerId: 'customer-42', }); ``` #### Set language explicitly ```js const session = await incode.createNewSession({ configurationId: 'YOUR_FLOW_ID', language: 'es-ES', }); ``` #### Store the token for later steps ```js 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. ```jsx 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. ```jsx onBoarding.renderRedirectToMobile(containerRef.current, { session: session, flowId: flowId, onSuccess: () => renderFinishScreen(), }); ``` **Options:** | Name | Type | Required | Description | | ------------------- | -------- | -------- | -------------------------------------------------- | | `session` | Object | Yes | Session object from `createSession`. | | `flowId` | String | No | ID of the flow to use on mobile. | | `onSuccess` | Function | Yes | Callback when mobile onboarding completes. | | `url` | String | No | URL to redirect to. | | `showSms` | Boolean | No | Shows the SMS component. | | `allowReEnrollment` | Boolean | No | Allows user re-enrollment. | | `externalId` | String | No | External ID to add to the URL. | | `assets` | Object | No | Assets from Dashboard. | | `expired` | Boolean | No | Indicates if the session expired. | | `smsText` | String | No | Custom SMS text. The URL is added after this text. | *** ## renderCombinedConsent Renders a combined consent interface configured in Dashboard. ```jsx renderCombinedConsent(consentElement, { token: session, onSuccess: () => console.log("Consent given"), consentId: "someConsentId", }); ``` **Parameters:** | Name | Type | Required | Description | | ----------- | ----------- | -------- | ---------------------------------------- | | `element` | HTMLElement | Yes | DOM element to render into. | | `consentId` | String | Yes | ID of a consent configured in Dashboard. | | `token` | Object | Yes | Session object from `createSession`. | | `onSuccess` | Function | Yes | Callback when consent is given. | *** ## sendGeolocation Requests the user's coordinates and sends them to the session. ```jsx onBoarding.sendGeolocation({ token }).then((res) => res); ``` **Parameters:** | Name | Type | Description | | ------- | ------ | --------------------- | | `token` | String | Session access token. | **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. ```jsx onBoarding.sendFingerprint({ token: session.token }).then((response) => { console.log(response.success); }); ``` **Parameters:** | Name | Type | Description | | ------- | ------ | --------------------- | | `token` | String | Session access token. | **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. ```jsx const { close } = renderCaptureId(myElement, { session: { token: 'YOUR_TOKEN' }, onSuccess: () => console.log('ID capture successful'), onError: (error) => console.error('ID capture failed:', error), }); ``` **Props:** | Name | Type | Required | Default | Description | | ------------- | -------- | -------- | ------- | -------------------------------------------------------------------------------------- | | `session` | Object | Yes | | Session object containing `token`. | | `onSuccess` | Function | Yes | | Callback after ID Capture completes. The component is unmounted before this is called. | | `onError` | Function | Yes | | Callback if an error occurs. Receives an `IdError` object or a standard `Error`. | | `forceIdV2` | Boolean | No | `false` | Forces the ID Capture v2 experience. | | `captureOnly` | Boolean | No | `false` | Forces capture-only mode: local capture, no upload. | **Returns:** `{ close: function }`. Call `close()` to unmount the component. **Error codes (**`IdError.code`**):** | Code | Description | | -------------------- | ------------------------------------------------------- | | `NO_MORE_TRIES` | User reached the maximum number of attempts. | | `PERMISSION_DENIED` | User denied camera permissions. | | `PERMISSION_REFRESH` | Camera permissions changed. A page refresh is required. | | `MODULE_NOT_FOUND` | Flow config does not include ID Capture. | | `WEBCAM_ERROR` | Camera failed to initialize or was not found. | | `FETCH_FLOW_ERROR` | Failed to fetch module configuration. | | `USER_CANCELED` | User cancelled the capture. | | `UNKOWN_ERROR` | Unknown error. | *** ## renderCaptureFace > Introduced in version 1.81.0. Initializes and renders the Face Capture module. > 📘 Note > > Starting in version 1.83.0, `processFace` is no longer called automatically at the end of `renderCaptureFace`. You must call it explicitly. ```jsx 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:** | Name | Type | Required | Default | Description | | ------------- | -------- | -------- | ------- | --------------------------------------------------------------------------------- | | `session` | Object | Yes | | Session object containing `token` | | `onSuccess` | Function | Yes | | Callback after successful capture. The component is unmounted first. | | `onError` | Function | Yes | | Callback if an error occurs. Receives a `FaceError` object or a standard `Error`. | | `forceV2` | Boolean | No | `false` | Forces the Face Capture v2 experience. | | `captureOnly` | Boolean | No | `false` | Forces capture-only mode: local capture, no upload. | **Returns:** `{ close: function }`. Call `close()` to unmount the component. **Error codes (**`FaceError.code`**):** | Code | Description | | ---------------------- | ------------------------------------------------------------ | | `NO_MORE_TRIES` | User reached the maximum number of attempts. | | `PERMISSION_DENIED` | User denied camera permissions. | | `PERMISSION_REFRESH` | Camera permissions changed. A page refresh is required. | | `MODULE_NOT_FOUND` | Flow config does not include Face Capture. | | `WEBCAM_ERROR` | Camera failed to initialize or was not found. | | `FETCH_FLOW_ERROR` | Failed to fetch module configuration. | | `USER_CANCELED` | User canceled the capture. | | `NONEXISTENT_CUSTOMER` | (`renderAuthFace` only) Hint doesn't match any customer. | | `HINT_NOT_PROVIDED` | (`renderAuthFace` only) Customer identity hint not provided. | | `UNKOWN_ERROR` | Unhandled server-side exception. | *** ## renderDocumentSelector Renders a Document Selector in a given container. Accepts the same parameters as `renderCamera`, excluding `type`. ```jsx renderDocumentSelector(element, { onSuccess: () => { /* success handler */ }, onError: () => { /* error handler */ }, }); ``` **Key Options:** | Name | Type | Default | Description | | ------------------- | -------- | ------- | -------------------------------------------------------- | | `onSuccess` | Function | | Callback when selection is successful. | | `onError` | Function | | Callback when an error occurs. | | `token` | Object | | Session token. | | `numberOfTries` | Number | `3` | Number of allowed attempts. | | `timeout` | Number | `40000` | Timeout in milliseconds. | | `showTutorial` | Boolean | `false` | Shows a tutorial. | | `nativeCamera` | Boolean | `false` | Uses the native camera; this allows PDF or image upload. | | `sendBase64` | Boolean | `true` | Send the image as base64. | | `fullScreen` | Boolean | `true` | Enables full-screen mode. | | `disableFullScreen` | Boolean | `false` | Uses container width and height instead of full screen. | | `scanPdf417` | Boolean | `false` | Scans for PDF417 barcodes. | | `isSecondId` | Boolean | `false` | Indicates this is a second ID. | *** ## renderCamera > For new integrations, use `renderCaptureId` and `renderCaptureFace` instead. Enables the device camera to capture an ID, selfie, or proof of address document. ```jsx incode.renderCamera("front", container, { onSuccess: myCallback, onError: console.log, numberOfTries: 3, token: session.token, }); ``` **Type Values (Capture Modes):** | Value | Description | | ------------------------ | ------------------------ | | `front` | Front side of ID | | `back` | Back side of ID | | `selfie` | Face capture | | `document` | Proof of address capture | | `passport` | Passport photo page | | `processCarInvoice` | Mexican car invoice | | `processCirculationCard` | Mexican circulation card | **Key Options:** | Name | Type | Default | Description | | ---------------------------------- | -------- | ------- | --------------------------------------------------------------------------- | | `onSuccess` | Function | | Callback after successful capture. | | `onError` | Function | | Callback when the maximum number of tries is reached. | | `token` | Object | | Session object. | | `numberOfTries` | Number | | Number of allowed capture attempts. Minimum: `1`. | | `timeout` | Number | | Milliseconds before enabling manual capture. | | `showTutorial` | Boolean | `false` | Shows a capture tutorial. | | `nativeCamera` | Boolean | | Uses the rear camera and allows PDF or image upload (`document` mode only). | | `assistedOnboarding` | Boolean | | Uses the rear camera for selfie. For assisted capture. | | `isRecordingEnabled` | Boolean | `false` | Records the capture session. | | `showCustomCameraPermissionScreen` | Boolean | | Shows custom permission instructions when camera access is denied. | | `hatCheckEnabled` | Boolean | | Checks for hats. | | `lensesCheckEnabled` | Boolean | | Checks for lenses. | | `maskCheckEnabled` | Boolean | | Checks for face masks. | | `eyesClosedCheckEnabled` | Boolean | | Checks for closed eyes. | **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. ```jsx 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. ```jsx const response = await onBoarding.processFace({ token }); ``` **Returns:** | Field | Type | Description | | -------------- | ------- | ---------------------------------------------- | | `confidence` | Nnumber | Face recognition confidence score from 0 to 1. | | `existingUser` | Boolean | Whether the user is already enrolled. | *** ## 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"}`. ```jsx 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:** | Name | Type | Default | Description | | ------------------------ | ------- | ------- | -------------------------------------------------------------------------------- | | `token` | Object | | Session object (required). | | `showTutorial` | Boolean | `false` | Shows a tutorial. | | `modules` | Array | all | Modules to include: `selfie`, `front`, `back`, `poa`, `questions`, and `speech`. | | `speechToTextCheck` | Boolean | `true` | Performs a speech-to-text check. | | `performLiveness` | Boolean | `false` | Enables liveness check. | | `videoSelfieAsSelfie` | Boolean | | Uses the video selfie image for face check instead of the selfie. | | `compareOCREnabled` | Boolean | `false` | Enables front OCR check. | | `compareIDEnabled` | Boolean | `true` | Enables front ID check. | | `questionsCount` | Number | `3` | Number of questions. | | `hatCheckEnabled` | Boolean | | Checks for hats. | | `lensesCheckEnabled` | Boolean | | Checks for lenses. | | `maskCheckEnabled` | Boolean | | Checks for face masks. | | `eyesClosedCheckEnabled` | Boolean | | Checks for closed eyes. | *** ## renderConference Renders the Video Conference module. ```jsx onBoarding.renderConference( container, { token: token, showOTP: false }, { onSuccess: (status) => { // status: 'close', 'deny', or 'approve' }, } ); ``` **Options:** | Name | Type | Default | Description | | --------------- | ------- | ------- | ------------------------------------------------------- | | `token` | Object | | Session object (required). | | `showOTP` | Boolean | | Shows the OTP screen before the conference. | | `numberOfTries` | Number | `3` | Number of OTP attempts allowed. Pass `-1` for no limit. | | `queue` | String | `''` | Conference queue. | **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. ```jsx IncodeSDK.renderAuthFace(container, { session: session, authHint: 'customer-uuid-12345', // omit for 1:N onSuccess: mySuccessCallbackFn, onError: myErrorCallbackFn, }); ``` **Options:** | Name | Type | Description | | ----------- | -------- | -------------------------------------------------- | | `session` | object | Session object (required) | | `authHint` | string | Customer UUID for 1:1 authentication. Omit for 1:N | | `onSuccess` | function | Callback after successful capture | | `onError` | function | Callback after max capture attempts reached | *** ## renderLogin > **Deprecated.** Use `renderAuthFace` instead. *** ## renderEnterCurp Renders the CURP entry and validation component (Mexico only). ```jsx incode.renderEnterCurp(document.getElementById('app'), { token: session.token, onSuccess: console.log, onError: console.log, }); ``` *** ## renderSignature Renders the Signature component for digital signature capture. ```jsx onBoarding.renderSignature(document.getElementById("app"), { token: session.token, onSuccess: console.log, onError: console.log, }); ``` **Options:** | Name | Type | Description | | ----------------------- | -------- | ----------------------------------------------------- | | `token` | string | Session token (required) | | `onSuccess` | function | Callback when signature upload succeeds | | `onError` | function | Callback when signature upload fails | | `type` | string | Signature type (for contract signing) | | `initials` | boolean | If `true`, capture initials instead of full signature | | `title` | jsx | Title element | | `subtitle` | jsx | Subtitle element | | `canvasBackgroundColor` | string | Canvas background color. Default: `#fff` | | `canvasBorderColor` | string | Canvas border color. Default: `#20263d` | | `penColor` | string | Pen color. Default: `#20263d` | *** ## addPhone Adds a phone number to the current session. Throws an error if a customer with that phone number already exists. ```jsx onBoarding.addPhone({ token, phone }).then((res) => res); ``` **Returns:** `{ success: true }` *** ## addCustomFields Adds custom fields to the current onboarding session. ```jsx 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`. ```jsx incode.renderBiometricConsent(document.getElementById("app"), { token: session, onSuccess: console.log, onCancel: console.log, regulationType: "US_Illinois", }); ``` **Options:** | Name | Type | Description | | ---------------- | -------- | ------------------------------------------------------------------------------------------------------ | | `token` | object | Session object from `createSession` | | `onSuccess` | function | Callback after consent is given | | `onCancel` | function | Callback after consent is cancelled | | `regulationType` | string | State string from `createSession`. Values: `US_California`, `US_Texas`, `US_Illinois`, `US_Washington` | *** ## renderMlConsent Renders the ML Consent component. ```jsx 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. ```jsx onBoarding.renderQr(containerRef.current, { session: session, flowId: flowId, onSuccess: () => showFinishScreen(), }); ``` **Options:** | Name | Type | Description | | ---------------- | -------- | ----------------------------------------- | | `session` | object | Session object (required) | | `flowId` | string | Flow ID to use on mobile | | `onSuccess` | function | Callback when mobile onboarding completes | | `url` | string | URL to redirect to | | `primaryColor` | string | Hex color string for styling | | `secondaryColor` | string | Hex color string for styling | | `sizePx` | number | QR code size in pixels (width and height) | *** ## renderQrScanner Renders a universal QR code scanner. Stores the QR value in the session as the `qrCodeText` custom field. ```jsx 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. ```jsx onBoarding.renderFiscalQr(document.getElementById("app"), { session: session, onSuccess() { console.log("Fiscal QR scanned"); }, }); ```