API Reference
Log inSign up
v1.7.3
v1.7.3
  • ComplyCube API Reference
  • Integration
  • Test and Live
  • Authentication
  • Rate Limits
  • Service Quota
  • Errors
  • Pagination
  • Filtering
  • Versioning
  • Core resources
    • Clients
      • Create a client
      • Get a client
      • Update a client
      • Delete a client
      • List clients
      • Filtering clients
    • Addresses
      • Create an address
      • Get an address
      • Update an address
      • Delete an address
      • List addresses
      • Filtering addresses
    • Documents
      • Create a document
      • Get a document
      • Update a document
      • Upload image attachment
      • Delete image attachment
      • Download image attachment
      • Redact image attachment
      • Delete a document
      • List documents
      • Filtering documents
    • Live Photos
      • Upload a live photo
      • Get a live photo
      • Download live photo
      • Redact live photo
      • Delete a live photo
      • List live photos
    • Live Videos
      • Get a live video
      • Redact live video
      • Delete live video
      • List live videos
    • Checks
      • Create a check
      • Get a check
      • Update a check
      • Validate check outcome
      • Redact check outcome
      • List checks
      • Filtering checks
    • Risk Profile
      • Get a risk profile
  • Check types
    • AML Screening Check
    • Document Check
    • Identity Check
    • Enhanced Identity Check
    • Proof of Address Check
    • Multi-Bureau Check
    • Face Authentication Check
    • Age Estimation Check
  • Lookups
    • Company Search
      • Search company
      • Get company details
    • Address Search
      • Search address
  • Tools
    • Custom Lists
      • Get a custom list
      • Add entity to custom list
      • List custom lists
  • Static Data
    • Screening Lists
    • Supported Documents
  • Other Resources
    • Flow (Hosted Solution)
      • Create a session
    • Webhooks
      • Create a webhook
      • Get a webhook
      • Update a webhook
      • Delete a webhook
      • List webhooks
      • Filtering webhooks
    • SDK Tokens
      • Generate a token
    • Autofill
      • Perform autofill
    • Reports
      • Generate a client report
      • Generate a check report
    • Team Members
      • Get a team member
      • List team members
      • Filtering team members
    • Audit Logs
      • Get an audit log
      • List audit logs
      • Filtering audit logs
    • Account Info
      • Get account info
  • Useful Resources
    • Testing Data
    • User Docs
Powered by GitBook
On this page
  • Run a document check
  • Image specifications
  • Check request
  • The options object
  • Example requests
  • Result object
  • Outcome
  • Breakdown
  • Sample response

Was this helpful?

  1. Check types

Document Check

Check your clients documents to extracts details and confirm their authenticity.

PreviousAML Screening CheckNextIdentity Check

Last updated 11 months ago

Was this helpful?

Run a document check

To run a Document Check, you must with the type set to document_check

The provided document must have an issuingCountry and associated image attachments that adhere to our .

The front side of the document will always be required. For certain , you should also provide the back side.

.

If the back side is not provided, our engine will conduct the check based on the front side alone. It is highly recommended to provide both sides of documents for more robust checks to take place.

Image specifications

Image attachments must comply with the following:

  • The images must be of good quality, with a minimum of 150 DPI.

  • The images must be either in JPG, PNG, or PDF format.

  • The images must be provided without blur or glare.

  • You must not take the image at an angle.

  • Each side of the document must be between 34 KB and 4 MB.

Check request

Attribute
Type
Description

clientId

string

The ID of the client associated with this check. (Required)

type

string

This must be set to document_check. (Required)

documentId

string

The ID of the document. (Required)

options

object

The options object

Attribute
Type
Description

analysisCoverage

array[string]

The types of analysis to conduct as part of a document check. Valid values include:

  1. consistency_analysis

  2. forensic_analysis

  3. content_analysis

  4. format_analysis

  5. front_back_analysis

  6. mrz_analysis

When this attribute is not provided, we will conduct all analysis types.

minimumPermittedAge

number

The minimum acceptable age before your client ID is flagged. When this attribute is not provided, we will default the minimum age to 18.

clientDataValidation

boolean

Adds an additional check that compares the client record data (first and last names) with data extracted from an ID document. When this attribute is not provided, it will default to false.

Example requests

Simple request

curl -X POST https://api.complycube.com/v1/checks \
     -H 'Authorization: <YOUR_API_KEY>' \
     -H 'Content-Type: application/json' \
     -d '{
               "clientId": "CLIENT_ID",
               "type": "document_check",
               "documentId": "DOCUMENT_ID"
        }'
const { ComplyCube } = require("@complycube/api");

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

const check = await complycube.check.create("CLIENT_ID", {
    type: "document_check",
    documentId: "DOCUMENT_ID"
});
from complycube import ComplyCubeClient

cc_api = ComplyCubeClient(api_key='<YOUR_API_KEY>')

check = cc_api.checks.create(
    'CLIENT_ID',
    'document_check', 
    documentId='DOCUMENT_ID'
)
use ComplyCube\ComplyCubeClient;

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

$result = $ccapi->checks()->create(
    'CLIENT_ID',
    [
        'type' => 'document_check',
        'documentId' => 'DOCUMENT_ID'
    ]
);
using ComplyCube.Net;
using ComplyCube.Net.Resources.Checks;

var checkApi = new CheckApi(new ComplyCubeClient("<YOUR_API_KEY>"));

var checkRequest = new CheckRequest {
  clientId = "CLIENT_ID",
  type = "document_check",
  documentId = "DOCUMENT_ID"
};

var check = await checkApi.CreateAsync(checkRequest);

Request with optional attributes

curl -X POST https://api.complycube.com/v1/checks \
     -H 'Authorization: <YOUR_API_KEY>' \
     -H 'Content-Type: application/json' \
     -d '{
               "clientId": "CLIENT_ID",
               "type": "document_check",
               "documentId": "DOCUMENT_ID",
               "options": {
                         "analysisCoverage": ["consistency_analysis", "content_analysis"],
                         "clientDataValidation": false
               }
        }'
const { ComplyCube } = require("@complycube/api");

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

const check = await complycube.check.create("CLIENT_ID", {
    type: "document_check",
    documentId: "DOCUMENT_ID",
    options: {
	analysisCoverage: ["consistency_analysis", "content_analysis"],
	clientDataValidation: false
    }
});
from complycube import ComplyCubeClient

cc_api = ComplyCubeClient(api_key='<YOUR_API_KEY>')

request = {
    'documentId': 'DOCUMENT_ID',
    'options': {
        'analysisCoverage': [
            'consistency_analysis',
            'content_analysis'
        ],
        'clientDataValidation': False
    }
}

check = cc_api.checks.create('CLIENT_ID', 'document_check', **request)
use ComplyCube\ComplyCubeClient;

$ccapi = new ComplyCubeClient('<YOUR_API_KEY>');
$check = [
    'type' => 'document_check',
    'documentId' => 'DOCUMENT_ID',
    'options' => [
        'analysisCoverage' => ['consistency_analysis', 'content_analysis'],
        'clientDataValidation' => false
    ]
];
$result = $ccapi->checks()->create('CLIENT_ID', $check);
using ComplyCube.Net;
using ComplyCube.Net.Resources.Checks;

var checkApi = new CheckApi(new ComplyCubeClient("<YOUR_API_KEY>"));

var checkRequest = new CheckRequest {
  clientId = "CLIENT_ID",
  type = "document_check",
  documentId = "DOCUMENT_ID"
};

checkRequest.options = new CheckRequestOptions {
  clientDataValidation = false,
  analysisCoverage = new string[] {
    "consistency_analysis",
    "content_analysis"
  }
};

var check = await checkApi.CreateAsync(checkRequest);

Result object

The result object is only returned when the status of the check is complete . It has two components - outcome and breakdown.

Outcome

The outcome attribute represents the overall check result. Returned values include:

  1. attention: Indicates at least one of the analysis results requires attention.

  2. not_processed: Indicates that ComplyCube was not able to process the images. Reasons include:

    • The image is of low quality.

    • The image is blurred or glared.

    • The image is at an angle.

    • The ID type and country provided do not correspond with the actual document provided uploaded.

Breakdown

The breakdown comprises the following objects:

extractedData object

  • documentDetails: Data relating to the document.

    • documentType: The detected document type. Values include:

      • passport

      • driving_license

      • national_identity_card

      • residence_permit

      • visa

      • unidentified

    • hasTwoSides: A boolean indicating if both sides of the document were used for the analysis.

    • documentNumber: The document number.

    • personalNumber: The personal number, if available.

    • issuingPlace: The issuing place of the document.

    • issuingAuthority: The issuing authority of the document.

    • additionalDetails: Any additional details extracted from the document. This will be returned as an array of key/value pair objects.

    • documentDiscriminator: The document discriminator.

    • cardAccessNumber: The card access number.

      • line1

      • line2

      • line3

  • holderDetails : Data relating to the document holder.

    • firstName: The list of first/given names as an array.

    • lastName: The list of last names as an array.

    • age: The age of the document holder. This will be a number.

    • birthPlace: The birthplace.

    • taxIdentificationNumber: The Tax Identification Number (TIN).

    • healthInsuranceNumber: The health insurance number.

    • gender: The gender. Values include:

      • male

      • female

      • other

  • allExtractedData: All the data extracted from the document, including data in native scripts, organized by source (e.g. Visual, MRZ, and barcode)

    • visual: All data extracted through the Visual Inspection Zone (VIZ).

    • mrz: All data extracted through the MRZ.

    • barcode: All data extracted through the barcode or QR code.

    • rfid: All data extracted through the RFID chip.

extractedImages array

The images extracted from the document. It's an array of type/data objects:

  • type: The extracted image type. Values include:

    • front_side

    • back_side

    • extracted_face

    • extracted_signature

    • extracted_security_element

    • extracted_code

    • extracted_fingerprint

  • data: The BASE64 encoded data content.

Analysis

For each conducted analysis, the returned values include:

  1. clear: Indicates the analysis returned a successful result.

  2. attention: Indicates a potential falsified or fraudulent document.

  3. not_processed: Returned when the analysis does not apply to a document type, e.g. MRZ Analysis on a document without an MRZ. It will also be returned if ComplyCube does not support a given country's particular analysis for a document type.

mrzAnalysis object

The MRZ analysis results. It has the following constituents:

  • mrzChecksum: Indicates whether the MRZ checksum test is valid.

  • mrzFormat: Indicates whether the MRZ format is valid.

rfidAnalysis object

The RFID chip analysis results. It has the following constituents:

  • basicAccessControl: Indicates whether the RFID chip passes a Basic Access Control (BAC) inspection.

  • chipAuthentication: Indicates whether the RFID chip is original and secure.

  • passiveAuthentication: Indicates whether the digital signature of the RFID chip is authentic and has not been tampered with.

  • activeAuthentication: Indicates whether the RFID chip passes our advanced dynamic authentication checks.

  • pace: Indicates whether the RFID chip passes the Password Authenticated Connection Establishment (PACE) inspection in line with standards.

  • chipAndVisualFacialSimilarity: Indicates whether the portrait image extracted from the RFID chip matches the one extracted from the visual ID document.

  • breakdown: Breakdown related to RFID analysis.

    • chipAndVisualFacialSimilarityScore: Indicates whether the portrait images extracted from the RFID chip and visual ID document are of the same person. The score will be 100 for a perfect match.

consistencyAnalysis object

The consistency analysis results. It has the following constituents:

  • firstName: Indicates whether the first name on the document and MRZ are consistent.

  • lastName: Indicates whether the last name on the document and MRZ are consistent.

  • dob: Indicates whether the birth date on the document and MRZ are consistent.

  • documentNumber: Indicates whether the document number on the document and MRZ are consistent.

  • personalNumber: Indicates whether the personal number on the document and MRZ are consistent.

  • issuingDate: Indicates whether issuing date on the document and MRZ are consistent.

  • expirationDate: Indicates whether the expiry date on the document and MRZ are consistent.

contentAnalysis object

The content analysis results. It has the following constituents:

  • dataIntegrity: Indicates whether the extracted data passes our integrity check.

  • issuingDate: Indicates whether issuing date has valid content.

  • expirationDate: Indicates whether the expiration date has valid content.

  • nationality: Indicates whether nationality has valid content.

  • specimenCheck: Indicates whether the content has been copied from the internet.

  • blackListCheck: Indicates a competent authority blacklisted the ID document.

formatAnalysis object

The format analysis results. It has the following constituents:

  • modelIdentification: Indicates whether the document model has been identified.

  • countryModelValidity: Indicates whether the document model adheres to the issuing country specifications.

  • documentModelValidity: Indicates whether the document model adheres to the document type specifications.

  • photocopyDetected: Indicates whether the document is a black and white photocopy.

forensicAnalysis object

The forensic analysis results. It has the following constituents:

  • documentLivenessCheck: Indicates if the document image is genuine and not a photo-of-an-image or photo-of-a-screen.

  • tamperingDetected: Indicates if the document image is tampered with using image manipulation software, such as Photoshop.

  • daylightAnalysis: Indicates whether the document daylight colours are valid.

  • mrzVisualPlacement: Indicates whether the MRZ is in the right location and not tampered with.

  • securityElements: Indicates whether the document security elements are valid.

  • photoLocation: Indicates whether the photo is in the correct location for a given document type.

  • mrzClassification: Indicates whether the MRZ is consistent with the document type.

  • breakdown: Breakdown related to forensic analysis.

    • documentFrontLivenessScore: Indicates the liveness score of the front side image of the document. The score will be 100 when it is assumed to be authentic.

    • documentBackLivenessScore: Indicates the liveness score of the back side image of the document. The score will be 100 when it is assumed to be authentic.

frontAndBackAnalysis object

The front and back of the image analysis results. It has the following constituents:

  • formatAnalysis: Indicates that both sides of the document are following the document type and country specifications.

  • dataConsistency: Indicates whether data on both sides of the document are consistent.

securityAndPatternAnalysis array

The security and pattern analysis results. It constitutes of an array of objects taking the following form:

  • expectedImageData: The BASE64 encoded data of the expected security element's pattern.

  • actualImageData: The BASE64 encoded data of the actual extracted security element pattern.

  • similarity: The similarity score between the expected and actual image patterns. The higher the score, the more likely the document is authentic.

  • outcome: The outcome of the analysis. This can be clear or attention.

  • narrative: A description of the analysis performed.

clientValidation object

The client validation results. It has the following constituents:

  • ageVerification: Indicates whether the extracted age is greater than or equal to a predefined minimum accepted age.

  • clientDataConsistency: Indicates whether the client data (e.g. first and last names) corresponds with data extracted from the ID.

Sample response

{
  "id": "5ebd40714f23960008c81527",
  "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",
            "observations": "OBSERVATIONS MADE BY ISSUING AUTHORITY"
          },
          "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"
          },
          "rfid": {
            "lastName": [
              "DOE"
            ],
            "firstName": [
              "JOHN"
            ],
            "dob": {
              "day": 3,
              "month": 9,
              "year": 1995
            },
            "documentNumber": "123456790",
            "issuingCountry": "US",
            "issuingDate": {
              "day": 15,
              "month": 11,
              "year": 2018
            },
            "expirationDate": {
              "day": 29,
              "month": 9,
              "year": 2026
            }
          }
        }
      },
      "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"
      },
      "rfidAnalysis": {
        "basicAccessControl": "clear",
        "chipAuthentication": "clear",
        "passiveAuthentication": "clear",
        "activeAuthentication": "clear",
        "pace": "clear",
        "chipAndVisualFacialSimilarity": "clear",
        "breakdown":{
          "chipAndVisualFacialSimilarityScore": 100
        }
      },
      "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"
}

The optional settings for the check. Also, see the object below. (Optional)

clear: Indicates every conducted returned a successful result, and hence the document is authentic.

The data extracted using . It has the following constituents:

issuingCountry: The issuing country of the document. This will be the .

expirationDate: The expiry date of the document. This will be a .

issuingDate: The issuing date of the document. This will be a .

mrz : The , which is usually at the bottom of the identity page of a passport or the back of an identity card, can be up to 3 lines depending on the document type:

dob: The date of birth. This will be a .

nationality: The nationality. This will be the .

analysis type
Optical Character Recognition (OCR)
two-letter country ISO code
Machine Readable Zone (MRZ)
two-letter country ISO code
create a check
document types
Learn about Document Checks
image specifications
structured date
structured date
structured date
options