Web SDK

Leverage our UX-optimised Web SDK to quickly verify your clients.

Overview

The ComplyCube Web SDK is a lightweight JavaScript library that lets you embed identity verification (IDV) flows directly into your web applications. It provides a ready-made, user-friendly widget for capturing documents, selfies, and proof of address, while handling quality detection and fraud signals under the hood.

Use the Web SDK if you want to:

Run verification flows inside your web app (instead of redirecting users to a hosted page).
Combine multiple verification stages (document capture, face capture, proof of address, etc.) into a single experience.
Easily customize branding, language, and callbacks for your business needs.

You’re viewing the check-driven SDK guide - an approach that provides detailed control but is best suited for partners or advanced use cases. We recommend using workflow integration for most implementations.

For a quick copy-paste example, see the Quick Integration Guide.

Integration modes

The Web SDK can be integrated in two different ways, depending on your needs:

Workflow Integration

Use the Workflow Designer to build your customer KYC journey and simply load it through the SDK. This is the better option for most use cases.

Recommended

Check-Driven Integration

A lower-level approach where you directly control individual SDK screens and checks. It's best suited for advanced use cases.

Integration flow

The Web SDK runs as part of your frontend but relies on your backend to create secure tokens. Here’s how it works:

Create a client

Generate an SDK token

Your backend requests a JWT token tied to that client.

Import and mount the SDK

Add the JS and CSS files, then mount the SDK in your web app.

Capture documents, videos, and selfies

The SDK guides your customer through the required steps.

Perform checks

Captured data is securely sent to ComplyCube for verification checks, and results are delivered in real time through the API or webhooks.

Integration guide

Create a client

Every verification flow starts with a client (i.e. customer). Use the API to create the client.

Example request

curl -X POST https://api.complycube.com/v1/clients \
     -H 'Authorization: <YOUR_API_KEY>' \
     -H 'Content-Type: application/json' \
     -d '{
          "type": "person",
          "email": "[email protected]",
          "personDetails":{
               "firstName": "John",
               "lastName" :"Doe"
          }
        }'

const { ComplyCube } = require("@complycube/api");

const complycube = new ComplyCube({ apiKey: "<YOUR_API_KEY>" });

const client = await complycube.client.create({
  type: "person",
  email: "[email protected]",
  personDetails: {
    firstName: "John",
    lastName: "Doe"
  }
});

from complycube import ComplyCubeClient
cc_api = ComplyCubeClient(api_key='<YOUR_API_KEY>')

new_client = {
    'type':'person',
    'email':'[email protected]',
    'personDetails': {
        'firstName':'John',
        'lastName':'Doe'
    }
}

client = cc_api.clients.create(**new_client)

use ComplyCube\ComplyCubeClient;

$ccapi = new ComplyCubeClient('<YOUR_API_KEY>');

$result = $ccapi->clients()->create([
    'type' => 'person',
    'email' => '[email protected]',
    'personDetails' => [
        'firstName' => 'John',
        'lastName' => 'Doe'
    ]
]);

using ComplyCube.Net;
using ComplyCube.Net.Resources.Clients;

var clientApi = new ClientApi(new ComplyCubeClient("<YOUR_API_KEY>"));
var newClient = new ClientRequest {
  type = "person",
  email = "[email protected]",
  personDetails = new PersonDetails {
    firstName = "John",
    lastName = "Doe"
  }
}

var client = await clientApi.CreateAsync(newclientRequest);

Example response

The response will contain an id (the Client ID). It is required for the next step.

{
    "id": "5eb04fcd0f3e360008035eb1",
    "type": "person",
    "email": "[email protected]",
    "personDetails": {
        "firstName": "John",
        "lastName": "Doe",
    },
    "createdAt": "2020-01-04T17:24:29.146Z",
    "updatedAt": "2020-01-04T17:24:29.146Z"
}

See Clients API Reference to learn more.

Generate an SDK token

Your backend must create an SDK token for each new flow. This token links the SDK session to the client. Tokens are short-lived and must not be reused.

Example request

curl -X POST https://api.complycube.com/v1/tokens \
     -H 'Authorization: <YOUR_API_KEY>' \
     -H 'Content-Type: application/json' \
     -d '{
          "clientId":"CLIENT_ID",
          "referrer": "https://www.example.com/*"
        }'

const { ComplyCube } = require("@complycube/api");

const complycube = new ComplyCube({ apiKey: "<YOUR_API_KEY>" });

const token = await complycube.token.generate("CLIENT_ID", {
    referrer: "https://www.example.com/*"
});

using ComplyCube.Net;
using ComplyCube.Net.Resources.SDKTokens;

var sdkTokenApi = new SDKTokenApi(new ComplyCubeClient("<YOUR_API_KEY>"));

var sdkTokenRequest = {
  clientId = "CLIENT_ID",
  referrer = "https://www.example.com/*"
}

var sdkToken = await sdkTokenApi.GenerateToken(sdkTokenRequest);

Example response

{
    "token": "<CLIENT_TOKEN>"
}

See SDK Token API Reference to learn more.

Import the SDK

To import our Web SDK, you need to include it in your target page HTML:

<!DOCTYPE html>
<html>
  <head>
    ...
    <!-- Importing the Javascript library -->
    <script src="complycube.min.js"></script>

    <!-- Importing the default CSS -->
    <link rel="stylesheet" href="style.css" />
  </head>
  <body>
     <!-- This is where the Web SDK will be mounted -->
    <div id="complycube-mount"></div>
  </body>
</html>

The links to complycube.min.js and style.css can be found in your developers portal.

Mount the SDK

With the generated SDK token, the Web SDK can be initialised in your frontend using the following Javascript code:

ComplyCube.mount({
  token: '<YOUR_WEB_SDK_TOKEN>',
  containerId: 'complycube-mount',
  stages: [
    'intro',
    'documentCapture',
    {
      name: 'faceCapture',
      options: {
        mode: 'video'
      }
    },
    'completion'
  ],
  onComplete: function(data) {
    // Using the data attributes returned, request your
    // backend server to perform the necessary ComplyCube checks
    console.info('Capture complete');
  },
  onModalClose: function() {
    // Handle the modal closure attempt
  },
  onError: function ({ type, message }) {
    if (type === 'token_expired') {
      // Request a new SDK token
    } else {
      // Handle other errors
      console.err(message);
    }
  }
});

The SDK mount parameters are described in the SDK Settings section below.

Referrer policy

To enable successful communication between the SDK and our servers, your web page's Referrer Policy header should be set to strict-origin-when-cross-origin. This ensures that the referrer information is securely transmitted during HTTP requests.

You can either do it programmatically or add it directly to the web page as follows: <meta name="referrer" content="strict-origin-when-cross-origin">

Perform checks

Using the data returned by the SDK, via the onComplete callback, you can now instruct your backend server to run the appropriate checks using the create a check endpoint.

For instance, use:

documentCapture.documentId to run a document check.
documentCapture.documentId and faceCapture.livePhotoId to run an identity check.
documentCapture.documentId and faceCapture.liveVideoId to run an enhanced identity check.
poaCapture.documentId to run a proof of address check.

If you have set up webhooks as described in our webhooks guide, you will be notified once a check completes.

To retrieve the check results, you can perform a get check request.

Example request

curl -X GET https://api.complycube.com/v1/checks/{:checkId} \
     -H 'Authorization: <YOUR_API_KEY>'

SDK reference

This section describes all configurable settings, callbacks, lifecycle methods, and branding options available in the ComplyCube Web SDK.

Settings

Option

Description

token

The SDK token generated by your backend. This is required. Type: string

containerId

The ID of the container element where the SDK mounts. This must be an empty element.

Type: string Default value: complycube-mount

useModal

This defines whether the UI screens load into a modal instead of inline. Type: boolean Default value: true

disableClientAnalytics

This defines whether we track client analytics or not.

Type: boolean Default value: false

stages

This is the list of stages your clients will go through. Stages can be provided as strings or as objects (to enable customization). See Stages below to learn more.

Type: array[object] or array[string]

Default values: ['intro', 'faceCapture, 'documentCapture', 'completion']

language

The UI language. Valid values include:

en , ar, br, de, es, fr, hi, hk, id, it, ja, ko, nl, no, pl, pt, sv, th, vi, zh

Type: string Default value: en

Callback

Callbacks let you respond to SDK lifecycle events.

Option

Description

onComplete

Triggered after the client completes the verification flow. Typically used to trigger a check on your backend.

Depending on the stages provided, data may include the following attributes:

documentCapture
- documentId: ID of the captured document.
- documentType: Type of document uploaded.
faceCapture
- liveVideoId: ID of the captured video. OR;
- livePhotoId: ID of the captired photo.
poaCapture
- documentId: ID of the uploaded proof of address document.
- documentType: Type of the uploaded proof of address document.

onError

Triggered when an error occurs. The error object has two attributes:

type: This can be:
- exception
- token_expired : indicates the token has expired. When this occurs, a new SDK token must be provided.
message: Description of the error.

onExit

This callback is triggered when your client exits before completing the flow. It will return the exit reason, e.g., USER_CONSENT_NOT_GRANTED.

onModalClose

Triggered when the client tries to close the modal. You can allow or prevent closure by updating the isModalOpen attribute using updateSettings.

Updating Settings

A number of settings can be updated at runtime as follows:

complycube = ComplyCube.mount({...});

// Replace the SDK token
complycube.updateSettings({ token: "NEW_SDK_TOKEN" });
...
// Open the modal
complycube.updateSettings({ isModalOpen: true });

//Close the modal
complycube.updateSettings({ isModalOpen: false });

Unmounting the SDK

If you are using the SDK in a Single Page Application (SPA), you can call the unmount function to remove the SDK and reset its state.

complycube = ComplyCube.mount({...});
...
complycube.unmount()

Stages

The stages array defines the verification flow. Each stage can be passed as a string or as an object with options.

Supported stage names

intro: Welcome screen.
userConsentCapture: Capture customer consent.
documentCapture: Capture ID documents.
faceCapture: Capture selfies or liveness videos.
poaCapture: Capture proof of address document.
completion: End of flow.

When userConsentCapture is enabled, always handle the onExit callback if the client declines consent.

Please make sure you pass the clientConsent parameter when consent is granted by your client.

When a stage is passed as object, it will have two attributes, name and options.

Name

This is the stage name

Options

This allows you to customize each stage as follows:

Stage Name

Options

intro

heading: Change the intro screen heading
message: A list of messages to display on the intro screen. Max size 3.
startButtonText: Change the text of the start button on the intro screen.

documentCapture

crossDeviceOnly: A boolean that indicates whether to force users to capture their document using their phone. This removes the document upload option.
documentTypes: The list of ID document types visible to the user. Valid document types include:
- passport
- driving_license
- national_identity_card
- residence_permit
Each value can be either a boolean or a country object. A boolean toggles the visibility of the document type, while a country object specifies the issuing country for non-passport documents, bypassing the country selection screen. The country value is the two-letter country ISO code.

faceCapture

mode: The mode of the facial capture. Possible values are: photo or video.

poaCapture

documentTypes: The list of Proof of Address (POA) document types visible to the client. Valid POA document types include:
- bank_statement
- utility_bill

The value of each document type is a boolean that toggles the visibility of the document type.

completion

heading: Change the completion screen heading.
message: A message to display on the completion screen. Max size 1.

Example options object

stages: [
  {
    name: "intro",
    options: {
      heading: "We need to verify your identity",
      message: [
        "In order to open an account, we need to check a few things.",
        "This will take only a moment",
      ],
      startButtonText: "Start Verification"
    },
  },
  "userConsentCapture",
  {
    name: "documentCapture",
    options: {
      crossDeviceOnly: true,
      documentTypes: {
        passport: true,
        driving_license: false,
        national_identity_card: true,
        residence_permit: {
          country: "GB",
        },
      },
    },
  },
  {
    name: "faceCapture",
    options: {
      mode: "video"
    },
  },
  {
    name: "poaCapture",
    options: {
      documentTypes: {
        bank_statement: true,
        utility_bill: false,
      },
    },
  },
  {
    name: "completion",
    options: {
      heading: "Thank you for completing the process",
      message: ["we will get in touch shortly"]
    },
  }
];

Branding

You can customise the SDK’s look and feel with the branding object. It comprises of the attributes outlined below.

Appearance

The appearance object allows you to customize the color scheme of the SDK with CSS values (e.g. RGBA, Hex). Customizable attributes include:

Attribute

Description

infoPopupColor

Warning popup background color

infoPopupTextColor

Warning popup background color

infoPopupLinkHoverColor

Warning popup fallback Link on hover background color

infoPopupLinkActiveColor

Warning popup fallback Link active background color

errorPopupColor

Error popup background color

errorPopupTextColor

Error popup text color

errorPopupLinkHoverColor

Error popup fallback Link on hover background color

errorPopupLinkActiveColor

Error popup fallback Link active background color

cameraButtonHoverColor

Camera button on hover background color

cameraButtonActiveColor

Camera button active background color

iconButtonActiveColor

Icon button active background color

iconButtonHoverColor

Icon button on hover background color

primaryButtonColor

Primary button background color

primaryButtonTextColor

Primary button text color

primaryButtonActiveColor

Primary button active background color

primaryButtonHoverColor

Primary button on hover background color

primaryButtonBorderColor

Primary button border color

secondaryButtonColor

Secondary button background color

secondaryButtonTextColor

Secondary button text color

secondaryButtonActiveColor

Secondary button active background color

secondaryButtonHoverColor

Secondary button on hover background color

secondaryButtonBorderColor

Secondary button border color

documentSelectorColor

Document selector background color

documentSelectorTextColor

Document selector text color

documentSelectorActiveBorderColor

Document selector active background color

documentSelectorHoverBorderColor

Document selector on the hover background color

linkHoverColor

Link on the hover background color

linkActiveColor

Link active background color

linkUnderlineColor

Link underline color

linkHoverTextColor

Link on the hover text color

bodyTextColor

SDK content text color

headingTextColor

SDK heading text color

subheadingTextColor

SDK subheading text color

Logo

The logo object has the following attributes:

lightLogoUrl: URL for your logo's light version
darkLogoUrl: URL for your logo's dark version

Example of logo branding

branding: {
  appearance: {
    primaryButtonColor: '#FF0000',
  },
  logo: {
    lightLogoUrl: 'light_logo_url',
    darkLogoUrl: 'dark_logo_url',
  }
},

Text Brand

The textBrand attribute represents the textual format of your brand.

Example of text branding

branding: {
  appearance: {
    primaryButtonColor: '#FF0000',
  },
  textBrand: 'Acme Bank'
}

If logo and textBrand attributes are specified at the same time, logo takes precedence.

Good morning

hashtagOverview

hashtagIntegration modes

hashtagIntegration flow

hashtagCreate a client

hashtagGenerate an SDK token

hashtagImport and mount the SDK

hashtagCapture documents, videos, and selfies

hashtagPerform checks

hashtagIntegration guide

hashtagCreate a client

hashtagExample request

hashtagExample response

hashtagGenerate an SDK token

hashtagExample request

hashtagExample response

hashtagImport the SDK

hashtagMount the SDK

hashtagReferrer policy

hashtagPerform checks

hashtagExample request

hashtagSDK reference

hashtagSettings

hashtagCallback

hashtagUpdating Settings

hashtagUnmounting the SDK

hashtagStages

hashtagSupported stage names

hashtagName

hashtagOptions

hashtagExample options object

hashtagBranding

hashtagAppearance

hashtagLogo

hashtagExample of logo branding

hashtagText Brand

hashtagExample of text branding

Overview

Integration modes

Integration flow

Create a client

Generate an SDK token

Import and mount the SDK

Capture documents, videos, and selfies

Perform checks

Integration guide

Create a client

Example request

Example response

Generate an SDK token

Example request

Example response

Import the SDK

Mount the SDK

Referrer policy

Perform checks

Example request

SDK reference

Settings

Callback

Updating Settings

Unmounting the SDK

Stages

Supported stage names

Name

Options

Example options object

Branding

Appearance

Logo

Example of logo branding

Text Brand

Example of text branding