Workflow Integration

Use workflows to integrate the Web SDK.

Overview

This guide walks you through integrating the Web SDK with ComplyCube workflows.

For a quick copy-paste example, use our integration assistant.

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 verification 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>

Loading the SDK with Integrity (Optional)

For additional security, you can optionally load the ComplyCube Web SDK using Subresource Integrity (SRI). This allows the browser to verify that the JavaScript and CSS files have not been modified by validating them against cryptographic checksums.

Retrieve the latest SDK integrity values

To ensure you always use the latest supported SDK version and integrity hashes, retrieve the asset metadata from the Web SDK info endpoint.

Example request

curl -X POST https://api.complycube.com/v1/webSdk/latest \
     -H 'Authorization: <YOUR_API_KEY>'

Example response

The response includes the URLs and corresponding integrity values for both the JavaScript and CSS assets.

{
  "js": {
    "url": "<JAVASCRIPT_ASSET_URL>/complycube.min.js",
    "integrity": "sha384-<INTEGRITY_HASH_1> sha384-<INTEGRITY_HASH_2>"
  },
  "css": {
    "url": "<CSS_ASSET_URL>/style.css",
    "integrity": "sha384-<INTEGRITY_HASH_1> sha384-<INTEGRITY_HASH_2>"
  }
}

Import the SDK using integrity attributes

Use the returned values to load the SDK in your HTML with integrity and crossorigin attributes:

<!DOCTYPE html>
<html>
  ...
  <head>
    <!-- Importing the Javascript library -->
    <script
      src="<JAVASCRIPT_ASSET_URL>/sdk.min.js"
      integrity="sha384-<INTEGRITY_HASH_1> sha384-<INTEGRITY_HASH_2>"
      crossorigin="anonymous">
    </script>

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

Notes

Using SRI is optional, but recommended for environments with stricter security requirements.
The crossorigin="anonymous" attribute is required when using SRI with assets served from a different origin.
Integrity values may change when the SDK is updated. Always retrieve the latest values from the endpoint.

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

Mount the SDK

As part of mounting the Web SDK, you are required to specify a workflow template ID. The SDK will automatically run the active version of the selected workflow.

Once the verification flow is complete, customers are redirected back to the return URL you specify.

With the generated 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',
  workflowTemplateId: "WORKFLOW_TEMPLATE_ID",
  onComplete: function(data) {    
    // Have your backend notify ComplyCube once the workflow is complete
    // to trigger the verification 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 verification checks

Once your customer starts the flow, a workflow session is automatically created. This session contains all captured data (documents, images, and videos) as well as progress tracking. You can view all of them through the workflow sessions page on the portal or through the API.

When the flow finishes, the SDK triggers the onComplete callback. The callback provides a data object that includes the workflowSessionId. Your backend should use this ID to notify ComplyCube that the workflow has completed, which in turn runs the verification checks defined in the workflow.

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

You can retrieve the details of a workflow session by calling the retrieve workflow session request.

Example of a complete workflow session request

curl -X POST https://api.complycube.com/v1/workflowSessions/{:wfSessionId}/complete \
     -H 'Authorization: <YOUR_API_KEY>' \
     -H 'Content-Type: application/json'

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

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

const wfSession = await complycube.workflowSession.complete("WORKFLOW_SESSION_ID");

using ComplyCube.Net;
using ComplyCube.Net.Resources.WorkflowSessions;

var wfSessionApi = new WorkflowSessionApi(new ComplyCubeClient("<YOUR_API_KEY>"));

var workflowSession = await wfSessionApi.CompleteAsync("WORKFLOW_SESSION_ID");

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

workflowTemplateId

The ID of the workflow template to load for this the session. 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

Callback

Callbacks let you respond to SDK lifecycle events.

Option

Description

onComplete

Triggered after the customer completes the verification flow. This is used to invoke a workflow session complete request.

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

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 flow

hashtagCreate a client

hashtagGenerate an SDK token

hashtagImport and mount the SDK

hashtagCapture documents, videos, and selfies

hashtagPerform verification checks

hashtagIntegration guide

hashtagCreate a client

hashtagGenerate an SDK token

hashtagImport the SDK

hashtagRetrieve the latest SDK integrity values

hashtagImport the SDK using integrity attributes

hashtagNotes

hashtagMount the SDK

hashtagReferrer policy

hashtagPerform verification checks

hashtagSDK reference

hashtagSettings

hashtagCallback

hashtagUpdating settings

hashtagUnmounting the SDK

hashtagBranding

hashtagAppearance

hashtagLogo

hashtagExample of logo branding

hashtagText Brand

hashtagExample of text branding

Overview

Integration flow

Create a client

Generate an SDK token

Import and mount the SDK

Capture documents, videos, and selfies

Perform verification checks

Integration guide

Create a client

Generate an SDK token

Import the SDK

Retrieve the latest SDK integrity values

Import the SDK using integrity attributes

Notes

Mount the SDK

Referrer policy

Perform verification checks

SDK reference

Settings

Callback

Updating settings

Unmounting the SDK

Branding

Appearance

Logo

Example of logo branding

Text Brand

Example of text branding