# 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(); ``` *** ## 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"); }, }); ```