Workflow Integration

Integrate KYC workflows in your web app using the ComplyCube 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": "john.doe@example.com",
          "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: "john.doe@example.com",
  personDetails: {
    firstName: "John",
    lastName: "Doe"
  }
});

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

new_client = {
    'type':'person',
    'email':'john.doe@example.com',
    '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' => 'john@doe.com',
    '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 = "john@doe.com",
  personDetails = new PersonDetails {
    firstName = "John",
    lastName = "Doe"
  }
}

var client = await clientApi.CreateAsync(newClient);

Example response

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

{
    "id": "5eb04fcd0f3e360008035eb1",
    "type": "person",
    "email": "john.doe@example.com",
    "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 initialized 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.error(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

useFullScreen

This defines whether the SDK loads in full-screen mode. Type: boolean Default value: false

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 colours, logos, and other branding elements through the branding settings page, if available on your plan.