Perform Document Check

Learn how to perform Document Check through the API.

Overview

This guide shows you how to run a Document check using the ComplyCube API.

You can try this check right away using our Demo Postman Collection. It’s publicly accessible and requires no account.

Integration steps

Create a client

The first step in creating any check is to add a client from your backend server. A client can represent either a person or a company.

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

Example request for creating a client

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",
               "dob": "1990-01-01"
          }
        }'

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",
    dob: "1990-01-01"
  }
});

from complycube import ComplyCubeClient

cc_api = ComplyCubeClient(api_key='<YOUR API KEY>')

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

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',
        'dob' => '1990-01-01'
    ]
]);

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",
        dob = "1990-01-01"
    }
}

var client = await clientApi.CreateAsync(newclient);

Example response

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

Create a document

Create a document by providing the Client ID and document type (e.g. passport, national ID).

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

Example request for creating a document

curl -X POST https://api.complycube.com/v1/documents \
     -H 'Authorization: <YOUR_API_KEY>' \
     -H 'Content-Type: application/json' \
     -d '{
          "clientId":"5eb04fcd0f3e360008035eb1",
          "type": "passport",
          "issuingCountry": "GB"
        }'

Example response

{
    "id": "5ebd40714f23960008c81527",
    "type": "passport",
    "issuingCountry": "GB",
    "createdAt": "2025-01-04T17:25:21.116Z",
    "updatedAt": "2025-01-04T17:25:21.116Z"
}

Upload front side of ID

Upload a BASE64-encoded image of the front of the ID document. Depending on the document type and issuing country, both sides may be required.

Images must be in JPG, PNG, or PDF format and between 34 KB and 4 MB in size.

Below is a sample BASE64-encoded file. Download it, copy its contents, and paste them into the data attribute when making the request.

Example request for uploading the front-side image of a document

 curl -X POST https://api.complycube.com/v1/documents/5ebd40714f23960008c81527/upload/front \
     -H 'Authorization: <YOUR_API_KEY>' \
     -H 'Content-Type: application/json' \
     -d '{
         "fileName": "front-test.jpg",
         "data": "<BASE64_DATA_CONTENT>"
        }'

var docFront = new ImageRequest {
  fileName = "front-test.jpg",
  data = "<BASE64_DATA_CONTENT>"
};

var img = await docApi.UploadImageAsync(
    "5ebd40714f23960008c81527", 
    "front", 
    docFront
);

Example response

{
    "id": "5eb169302d868c0008828591",
    "fileName": "front-test.jpg",
    "documentSide": "front",
    "downloadLink": "/documents/5ebd40714f23960008c81527/images/5eb169302d868c0008828591/download",
    "contentType": "image/jpg",
    "size": 72716,
    "createdAt": "2025-01-04T17:25:21.116Z",
    "updatedAt": "2025-01-04T17:25:21.116Z"
}

Create a check

Create a check by specifying the Client ID, Document ID, and the check type.

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

Example request for creating a check

curl -X POST https://api.complycube.com/v1/checks \
     -H 'Authorization: <YOUR_API_KEY>' \
     -H 'Content-Type: application/json' \
     -d '{
          "clientId":"5eb04fcd0f3e360008035eb1",
          "documentId":"5ebd40714f23960008c81527",
          "type": "document_check"
        }'

var checkRequest = new CheckRequest {
  clientId = "5eb04fcd0f3e360008035eb1",
  documentId = "5ebd40714f23960008c81527",
  type = "document_check"
};

var check = await checkApi.CreateAsync(checkRequest);

Example response

{
    "id": "65c12a6426d2ab000814037e",
    "entityName": "John Doe",
    "type": "document_check",
    "clientId": "5eb04fcd0f3e360008035eb1",
    "documentId": "5ebd40714f23960008c81527",
    "status": "pending",
    "createdAt": "2025-01-04T17:25:21.116Z",
    "updatedAt": "2025-01-04T17:25:21.116Z"
}

Retrieve results

ComplyCube will then run the check. You can retrieve its outcome and detailed breakdown via the API, or review the results in the Portal.

If you have set up webhooks, you’ll also receive a notification once the check is complete.

Example request for retrieving the check outcome

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

Example response

{
  "id": "65c12a6426d2ab000814037e",
  "clientId": "5eb04fcd0f3e360008035eb1",
  "documentId": "5ebd40714f23960008c81527",
  "entityName": "John Doe",
  "type": "document_check",
  "status": "complete",
  "result": {
    "outcome": "clear",
    "breakdown": {
      "extractedData": {
        "documentDetails": {
          "documentType": "driving_license",
          "hasTwoSides": true,
          "issuingCountry": "GB",
          "issuingDate": {
            "day": 1,
            "month": 1,
            "year": 2015
          },
          "expirationDate": {
            "day": 1,
            "month": 1,
            "year": 2025
          },
          "documentNumber": "123456790",
          "personalNumber": "123456790"
        },
        "holderDetails": {
          "lastName": [
            "DOE"
          ],
          "firstName": [
            "JOHN"
          ],
          "dob": {
            "day": 3,
            "month": 9,
            "year": 1995
          },
          "address": {
            "addressText": "110 MAPLE ROAD, SAMPLE CITY, NC 10000-0008",
            "line": "110 MAPLE ROAD",
            "city": "SAMPLE CITY",
            "state": "North Carolina",
            "postalCode": "10000-0008",
            "country": "US"
          }
        }
      },
      "allExtractedData": {
        "visual": {
          "lastName": [
            "DOE"
          ],
          "firstName": [
            "JOHN"
          ],
          "dob": {
            "day": 3,
            "month": 9,
            "year": 1995
          },
          "age": 26,
          "gender": "male",
          "documentNumber": "123456790",
          "documentDiscriminator": "123456790",
          "issuingDate": {
            "day": 1,
            "month": 1,
            "year": 2015
          },
          "expirationDate": {
            "day": 1,
            "month": 1,
            "year": 2025
          },
          "addressText": "110 MAPLE ROAD, SAMPLE CITY, NC 10000-0008",
          "addressLine": "110 MAPLE ROAD",
          "addressCity": "SAMPLE CITY",
          "addressPostalCode": "10000-0008",
          "height": "175 cm"
        },
        "barcode": {
          "lastName": [
            "DOE"
          ],
          "firstName": [
            "JOHN"
          ],
          "dob": {
            "day": 3,
            "month": 9,
            "year": 1995
          },
          "gender": "male",
          "documentNumber": "123456790",
          "documentDiscriminator": "123456790",
          "issuingCountry": "US",
          "issuingDate": {
            "day": 15,
            "month": 11,
            "year": 2018
          },
          "expirationDate": {
            "day": 29,
            "month": 9,
            "year": 2026
          },
          "addressText": "110 MAPLE ROAD, SAMPLE CITY, NC 10000-0008",
          "addressLine": "110 MAPLE ROAD",
          "addressCity": "SAMPLE CITY",
          "addressPostalCode": "10000-0008",
          "addressState": "North Carolina",
          "addressCountry": "US",
          "height": "175 cm"
        }
      }
    },
    "mrzAnalysis": {
      "mrzFormat": "clear",
      "mrzChecksum": "clear"
    },
    "consistencyAnalysis": {
      "lastName": "clear",
      "firstName": "clear",
      "dob": "clear",
      "documentNumber": "clear",
      "personalNumber": "clear",
      "expirationDate": "clear",
      "issuingDate": "clear"
    },
    "contentAnalysis": {
      "dataIntegrity": "clear",
      "issuingDate": "clear",
      "expirationDate": "clear",
      "specimenCheck": "clear",
      "blackListCheck": "clear"
    },
    "formatAnalysis": {
      "modelIdentification": "clear",
      "countryModelValidity": "clear",
      "documentModelValidity": "clear",
      "photocopyDetected": "clear"
    },
    "forensicAnalysis": {
      "documentLivenessCheck": "clear",
      "tamperingDetected": "clear",
      "mrzVisualPlacement": "clear",
      "securityElements": "clear",
      "photoLocation": "clear",
      "mrzClassification": "clear",
      "breakdown": {
        "documentFrontLivenessScore": 100,
        "documentBackLivenessScore": 100
      }
    },
    "frontAndBackAnalysis": {
      "formatAnalysis": "clear",
      "dataConsistency": "clear"
    },
    "clientValidation": {
      "ageVerification": "clear",
      "clientDataConsistency": "clear"
    },
    "extractedImages": [{
      "type": "front_side",
      "data": "<BASE64_IMAGE_CONTENT>"
    }],
    "securityAndPatternAnalysis": [{
      "similarity": 100,
      "outcome": "clear",
      "narrative": "Clear",
      "actualImageData": "<BASE64_IMAGE_CONTENT>",
      "expectedImageData": "<BASE64_IMAGE_CONTENT>"
    }]
  },
  "createdAt": "2020-01-01T14:06:44.756Z",
  "updatedAt": "2020-01-01T14:06:91.913Z"
}

PreviousPerform AML Screening NextPerform Identity Check

Good afternoon

hashtagOverview

hashtagIntegration steps

hashtagCreate a client

hashtagCreate a document

hashtagUpload front side of ID

hashtagCreate a check

hashtagRetrieve results

Overview

Integration steps

Create a client

Create a document

Upload front side of ID

Create a check

Retrieve results