Check-Driven Integration

Build hosted KYC verification journeys with direct control over checks handling.

Overview

This guide walks you through integrating the Hosted Solution with ComplyCube using the check-driven approach, giving you direct control over individual verification steps.

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

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.

Integration guide

ComplyCube's Hosted Solution requires a Hosted Solution session to be initiated by your backend. Here’s how it works:

Create a client

Every Hosted Solution session 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 a Hosted Solution session

A Hosted Solution session creates a unique ComplyCube URL that you can use to redirect your customers to complete their identity verification. Once complete, your clients will be redirected to your chosen URL.

Example request

curl -X POST https://api.complycube.com/v1/flow/sessions \
     -H 'Authorization: <YOUR_API_KEY>' \
     -H 'Content-Type: application/json' \
     -d '{
          "clientId":"CLIENT_ID",
          "checkTypes": ["extensive_screening_check", "identity_check", "document_check"],
          "successUrl": "https://www.yoursite.com/success",
          "cancelUrl": "https://www.yoursite.com/cancel"
        }'

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

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

const session = await complycube.flow.createSession("CLIENT_ID", {
    checkTypes: [
      "extensive_screening_check",
      "identity_check",
      "document_check"
    ],
    successUrl: "https://www.yoursite.com/success",
    cancelUrl: "https://www.yoursite.com/cancel",
    theme: "light"
});

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

flow_session = {
    'clientId': client.id,
    'checkTypes':[
        'extensive_screening_check',
        'identity_check',
        'document_check'
    ],
    'successUrl':'https://www.yoursite.com/success',
    'cancelUrl':'https://www.yoursite.com/cancel',
    'theme': 'light'
}

session = cc_api.flow.create(**flow_session)

use ComplyCube\ComplyCubeClient;

$ccapi = new ComplyCubeClient('<YOUR_API_KEY>');
$session = $ccapi->flow()->createSession([
    'clientId' => $clientId,
    'checkTypes' => [
        'extensive_screening_check',
        'identity_check',
        'document_check'
    ],
    'successUrl' => 'https://www.yoursite.com/success',
    'cancelUrl' => 'https://www.yoursite.com/cancel',
    'theme' => 'light'
]);

using ComplyCube.Net;
using ComplyCube.Net.Resources.FlowSessions;

var fSession = new FlowSessionApi(new ComplyCubeClient("<YOUR_API_KEY>"));

var flowSession = new FlowSessionRequest {
  clientId = aClient.id,
  checkTypes = new string[] {
    "extensive_screening_check",
    "identity_check",
    "document_check"
  },
  successUrl = "http://complycube.com",
  cancelUrl = "http://complycube.com"
};

var result = fSession.CreateAsync(flowSession).Result;

Example response

{
    "redirectUrl": "https://flow.complycube.com/test_ODdkNjhiOTU0MzY4YmE5NjRmMDMyY2E5MWYwZjgxNjMzZTcyMWJmNzU2YjZmNDQ4NmFjMTU0ZGZhYTU5MmNhY2NiNjI3ZDE4YWJkYmU2M2M3ZWYzZTlmM2M3MzgxMmM3NzZhMjVlYmQyNDI0ODdkOWQ3M2JiMjkxZTYxNzdhYmExMGEzOGRhYmM2OTIwMjgyYmEzZGY3ZDY0NWZhMjcwN2RlMTFkOTcxZWNhOWI2Zjg0NjllZGNkODVjYzMzMDA5YjdlMWY5OGIwMmZjY2UzNGI2YTMxOGQxNGZmNGFhYjczNzU0YmYwMjFkMzU1M2FjMjQ4ZDQ2ZjJjZTY4YWY0MzIxNjVlMDRjOTIyYTExMTlmMWU3YTYwMDY1NGJmYWM0NTA2MDE5NTg5NTkxYzA4MzYyYTUyM2I0NDM4OGExNWIyMTIzYTBhNDc0NDA4NWM2ZTQwMmNjMGVjMTk2YW"
}

See Flow Sessions API Reference to learn more.

Redirect the client to the URL

Redirect your client to the redirectUrl generated in the previous step. Once the customer completes the flow on the hosted solution:

ComplyCube will automatically run the checks you selected when creating the session (as specified in checkTypes).
The customer will be redirected to the successUrl you provided.

You can access the results and a detailed breakdown of each check via the API or Web Portal. If you’ve configured webhooks, ComplyCube will send a notification upon completion of each check.

Branding

You can customize colors, logos, and other branding elements through the brand settings page, if available on your plan.