Document Check

What kind of data I will get

By using this integration you will be able to verify identity customers' documents.

Integration Scope

You can choose which of the document types user will be allowed to pass. These include

• national identity card

• driving licence

• passport

• resident permit

Input

You can configure users' input that will be send to comply cube in order to get the most of the verifications.

Field	Description	Type	Required
email	The client's email address.	string	Yes
mobile	The client's mobile number.	string	No
telephone	The client's telephone number.	string	No
joinedDate	The date and time when the client was registered with you. This is relevant for users that migrate existing customers.	string (format YYYY-MM-DD)	No
personDetails	Primary details for a client of type person	object	Yes if client is of type person
companyDetails	Primary details for a client of type company	object	Yes if client is of type company
address	Primary details of a client's address	object	Yes if proof of address check is selected

PersonDetails

Field	Description	Type	Required
firstName	The client's first name.	string	Yes (required when client is a person)
middleName	The client's middle name.	string	No
lastName	The client's last name.	string	Yes (required when client is a person)
dob	The client's date of birth.	string (format YYYY-MM-DD)	No
gender	The client's gender.	string (possible values include: male, female, other)	No
nationality	The client's nationality.	string (2 letter country ISO code)	No
birthCountry	The client's birth country.	string (2 letter country ISO code)	No
ssn	The client's SSN (Social Security Number). This is for US clients.	string	No
socialInsuranceNumber	The client's Social Insurance Number.	string	No
nationalIdentityNumber	The client's National Identity Number.	string	No
taxIdentificationNumber	The client's Tax Identification Number (TIN).	string	No

CompanyDetails

Field	Description	Type	Required
name	Name of the company.	string	Yes (required if client is company)
website	Website of the company.	string	No
registrationNumber	Registration number of the company.	string	No
incorporationCountry	Country where the company is incorporated.	string (2 letter country ISO code)	No
incorporationType	Type of incorporation of the company.	string (possible values include: sole_proprietorship private_limited_company public_limited_company limited_partnership holding_company non_government_organisation statutory_company subsidiary_company unlimited_partnership charitable_incorporated_organisation chartered_company)	No

Input Example

{
    "email": "[email protected]",
    "personDetails": {
        "firstName": "Jan",
        "lastName": "Kowalskii"
    }
}

Output

Attribute	Type	Description
client	object	Comply Cube client details.
checksResult	map	Results of performed checks.

Client

Attribute	Type	Description
id	string	The unique identifier for a client.
type	string, possible values include: person company	The type of client.
entityName	string	The client's full name.
email	string	The client's email address.
personDetails	object	Details for a client of type person.
companyDetails	object	Details for a client of type company.
createdAt	string	The date and time when the client was created.
updatedAt	string	The date and time when the client was updated.

Person Details

Attribute	Type	Description
firstName	string	The client's first name.
lastName	string	The client's last name.

Company Details

Attribute	Type	Description
name	string	The client's name.

Checks Result

Attribute	Type	Description
documentCheck	string	Result of the document check.

Document Check

Attribute	Type	Description
state	string, possible values include: INIT IN_PROGRESS ERROR FAILED FINISHED	The status of the client's verification
document	object	Document which was used to verification process.
files	links	Links that allow to download client's documents.
outcome	string, possible values include: clear attention not_processed	The outcome attribute represents the overall check result. Returned values include: clear: Indicates every analysis type conducted returned a successful result, and hence the document is authentic. attention: Indicates at least one of the analysis results requires attention. 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	object	Details of verification.
mrzAnalysis	object	The MRZ analysis results.
consistencyAnalysis	object	The consistency analysis results.
contentAnalysis	object	The content analysis results.
formatAnalysis	object	The format analysis results.
forensicAnalysis	object	The forensic analysis results.
frontAndBackAnalysis	object	The front and back of the image analysis results.
clientValidation	object	The client validation results.
extractedImages	array<object>	The images extracted from the document.
securityAndPatternAnalysis	object	The security and pattern analysis results.

Document

Attribute	Type	Description
type	string, valid values include: passport driving_license national_insurance_number social_security_number utility_bill tax_identification_number national_identity_card visa polling_card residence_permit birth_certificate bank_statement change_of_name tax_document company_confirmation_statement company_annual_accounts company_statement_of_capital company_change_of_address company_incorporation company_change_of_officers company_change_of_beneficial_owners unknown other	The type of document.
issuingCountry	string	The document's issuing country. This will be the two-letter country ISO code.
createdAt	string	The date and time when the document was created.
updatedAt	string	The date and time when the document was updated.

Breakdown

Attribute	Type	Description
extractedData	object	The data extracted using Optical Character Recognition (OCR).
allExtractedData	object	All the data extracted from the document, including data in native scripts, organized by source (e.g. Visual, MRZ, and barcode)

Extracted Data

Attribute	Type	Description
documentDetails	object	Data relating to the document.
holderDetails	object	Data relating to the document holder.

Document Details

Property	Type	Description
documentType	string, possible values include: passport driving_license national_identity_card residence_permit visa unidentified	Detected document type.
hasTwoSides	boolean	A boolean indicating if both sides of the document were used for the analysis.
issuingCountry	string	The issuing country of the document. This will be the two-letter country ISO code.
expirationDate	object	Expiry date of the document.
documentNumber	string	Document number.
personalNumber	string	Personal number (if available).
issuingDate	object	Issuing date of the document.
issuingPlace	string	Issuing place of the document.
issuingAuthority	string	Issuing authority of the document.
additionalDetails	array	Any additional details extracted from the document. This will be returned as an array of key/value pair objects.
documentDiscriminator	string	Document discriminator.
cardAccessNumber	string	Card access number.
mrz	object	The Machine Readable Zone (MRZ), 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: line1 line2 line3

Holder Details

Property	Type	Description
firstName	array<string>	The list of first/given names as an array.
lastName	array<string>	The list of last names as an array.
dob	object	The date of birth.
age	number	The age of the document holder.
birthPlace	string	Birthplace.
nationality	string	The nationality. This will be the two-letter country ISO code.
taxIdentificationNumber	string	Tax Identification Number (TIN).
healthInsuranceNumber	string	Health insurance number.
gender	string, values include: male female other	Gender of the document holder.

Date

Attribute	Type	Description
day	number	The day of the month. Value range 1-31.
month	number	The month. Value range 1-12.
year	number	The year, in YYYY format.

All extracted Data

Attribute	Type	Description
visual	object	All data extracted through the Visual Inspection Zone (VIZ).
barcode	object	All data extracted through the barcode or QR code.
mrz	object	All data extracted through the MRZ.

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.

MRZ Analysis

Attribute	Type	Description
mrzFormat	string	Indicates whether the MRZ checksum test is valid.
mrzChecksum	string	Indicates whether the MRZ checksum test is valid.

Consistency Analysis

Attribute	Type	Description
lastName	string	Indicates whether the first name on the document and MRZ are consistent.
firstName	string	Indicates whether the last name on the document and MRZ are consistent.
dob	string	Indicates whether the birth date on the document and MRZ are consistent.
documentNumber	string	Indicates whether the document number on the document and MRZ are consistent.
personalNumber	string	Indicates whether the personal number on the document and MRZ are consistent.
expirationDate	string	Indicates whether the expiry date on the document and MRZ are consistent.
issuingDate	string	Indicates whether issuing date on the document and MRZ are consistent.

Content Analysis

Attribute	Type	Description
dataIntegrity	string	Indicates whether the extracted data passes our integrity check.
issuingDate	string	Indicates whether issuing date has valid content.
expirationDate	string	Indicates whether the expiration date has valid content.
nationality	string	Indicates whether nationality has valid content.
specimenCheck	string	Indicates whether the content has been copied from the internet.
blackListCheck	string	Indicates a competent authority blacklisted the ID document.

Format Analysis

Attribute	Type	Description
modelIdentification	string	Indicates whether the document model has been identified.
countryModelValidity	string	Indicates whether the document model adheres to the issuing country specifications.
documentModelValidity	string	Indicates whether the document model adheres to the document type specifications.
photocopyDetected	string	Indicates whether the document is a black and white photocopy.

Forensic Analysis

Attribute	Type	Description
documentLivenessCheck	string	Indicates if the document image is genuine and not a photo-of-an-image or photo-of-a-screen.
tamperingDetected	string	Indicates if the document image is tampered with using image manipulation software, such as Photoshop.
daylightAnalysis	string	Indicates whether the document daylight colours are valid.
mrzVisualPlacement	string	Indicates whether the MRZ is in the right location and not tampered with.
securityElements	string	Indicates whether the document security elements are valid.
photoLocation	string	Indicates whether the photo is in the correct location for a given document type.
mrzClassification	string	Indicates whether the MRZ is consistent with the document type.
breakdown	object	Breakdown related to forensic analysis.

Forensic Analysis Breakdown

Attribute	Type	Description
documentFrontLivenessScore	number	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	number	Indicates the liveness score of the back side image of the document. The score will be 100 when it is assumed to be authentic.

Front And Back Analysis

Attribute	Type	Description
formatAnalysis	string	Indicates that both sides of the document are following the document type and country specifications.
dataConsistency	string	Indicates whether data on both sides of the document are consistent.

Client Validation

Attribute	Type	Description
ageVerification	string	Indicates whether the extracted age is greater than or equal to a predefined minimum accepted age.
clientDataConsistency	string	Indicates whether the client data (e.g. first and last names) corresponds with data extracted from the ID.

Extracted Images

Property	Type	Description
type	string, possible values include: front_side back_side extracted_face extracted_signature extracted_security_element extracted_code extracted_fingerprint	Extracted image type.
data	string	BASE64 encoded image data.

Security And Pattern Analysis

Attribute	Type	Description
similarity	string	The similarity score between the expected and actual image patterns. The higher the score, the more likely the document is authentic.
outcome	string	The outcome of the analysis. This can be clear or attention.
narrative	string	A description of the analysis performed.
actualImageData	string	The BASE64 encoded data of the actual extracted security element pattern.
expectedImageData	string	The BASE64 encoded data of the expected security element's pattern.

Output Example

{
    "complyCube": {
        "documentCheck": [
            {
                "client": {
                    "id": "64e369e520b96f0008d945bf",
                    "type": "person",
                    "entityName": "Jan Kowalski",
                    "email": "[email protected]",
                    "personDetails": {
                        "firstName": "Jan",
                        "lastName": "Kowalski"
                    },
                    "createdAt": "2023-08-21T13:43:01.539Z",
                    "updatedAt": "2023-08-21T13:43:01.539Z"
                },
                "checksResult": {
                    "documentCheck": {
                        "state": "FINISHED",
                        "outcome": "attention",
                        "document": {
                            "type": "NATIONAL_IDENTITY_CARD",
                            "classification": "PROOF_OF_IDENTITY",
                            "createdAt": "2023-08-21T13:43:15.410Z",
                            "updatedAt": "2023-08-21T13:43:18.796Z"
                        },
                        "files": [
                            {
                                "resourceId": "e89f45e5-7f71-4886-8a3a-241f1f8315bb",
                                "resourcePath": "resources/b6e595f4-0682-4b9e-ac09-30da50b4e591/e89f45e5-7f71-4886-8a3a-241f1f8315bb/b5188051-db1f-4d09-a5c6-52b29c86794f/fake_dowod_front.png",
                                "resourceName": "dowod_front.png"
                            },
                            {
                                "resourceId": "6bb71612-4265-4546-a382-ffe283bb9c06",
                                "resourcePath": "resources/b6e595f4-0682-4b9e-ac09-30da50b4e591/6bb71612-4265-4546-a382-ffe283bb9c06/b5188051-db1f-4d09-a5c6-52b29c86794f/fake_dowod_back.png",
                                "resourceName": "dowod_back.png"
                            }
                        ],
                        "outcome": "attention",
                        "breakdown": {
                            "extractedData": {
                                "holderDetails": {
                                    "lastName": [
                                        "KOWALSKI"
                                    ],
                                    "firstName": [
                                        "JAN"
                                    ],
                                    "dob": {
                                        "day": 2,
                                        "month": 1,
                                        "year": 1981
                                    },
                                    "age": 42,
                                    "nationality": "PL",
                                    "birthPlace": "WARSZAWA",
                                    "gender": "male"
                                },
                                "documentDetails": {
                                    "documentNumber": "ZZC108201",
                                    "documentType": "national_identity_card",
                                    "documentSubtypes": [
                                        "Poland - Id Card (2021) Side B",
                                        "Poland - Id Card (2021)"
                                    ],
                                    "issuingCountry": "PL",
                                    "issuingAuthority": "PREZYDENT M. ST. WARSZAWY",
                                    "issuingDate": {
                                        "day": 2,
                                        "month": 8,
                                        "year": 2021
                                    },
                                    "expirationDate": {
                                        "day": 2,
                                        "month": 8,
                                        "year": 2031
                                    },
                                    "personalNumber": "81010200131",
                                    "cardAccessNumber": "123456",
                                    "hasTwoSides": true
                                },
                                "allExtractedData": {
                                    "visual": {
                                        "lastName": [
                                            "KOWALSKI"
                                        ],
                                        "lastNameNative": "KOWALSKI",
                                        "firstName": [
                                            "JAN"
                                        ],
                                        "firstNameNative": "JAN",
                                        "entityNameNative": "KOWALSKI JAN",
                                        "dob": {
                                            "day": 2,
                                            "month": 1,
                                            "year": 1981
                                        },
                                        "nationalityNative": "POLSKIE",
                                        "birthPlace": "WARSZAWA",
                                        "birthPlaceNative": "WARSZAWA",
                                        "gender": "male",
                                        "documentNumber": "ZZC108201",
                                        "personalNumber": "81010200131",
                                        "cardAccessNumber": "123456",
                                        "issuingAuthority": "PREZYDENT M. ST. WARSZAWY",
                                        "issuingAuthorityNative": "PREZYDENT M. ST. WARSZAWY",
                                        "issuingDate": {
                                            "day": 2,
                                            "month": 8,
                                            "year": 2021
                                        },
                                        "expirationDate": {
                                            "day": 2,
                                            "month": 8,
                                            "year": 2031
                                        }
                                    },
                                    "mrz": {
                                        "lastName": [
                                            "KOWALSKI"
                                        ],
                                        "firstName": [
                                            "JAN"
                                        ],
                                        "dob": {
                                            "day": 2,
                                            "month": 1,
                                            "year": 1981
                                        },
                                        "nationality": "PL",
                                        "gender": "male",
                                        "documentNumber": "ZZC108201",
                                        "personalNumber": "81010200131",
                                        "issuingCountry": "PL",
                                        "expirationDate": {
                                            "day": 2,
                                            "month": 8,
                                            "year": 2031
                                        }
                                    },
                                    "barcode": {
                                        "cardAccessNumber": "123456"
                                    }
                                },
                                "mrz": {
                                    "line1": "I<POLZZC1082012<<<<<<<<<<<<<<<",
                                    "line2": "8101028M3108022POL810102001312",
                                    "line3": "KOWALSKI<<JAN<<<<<<<<<<<<<<<<<"
                                }
                            },
                            "mrzAnalysis": {
                                "mrzChecksum": "attention",
                                "mrzFormat": "attention"
                            },
                            "contentAnalysis": {
                                "expirationDate": "clear",
                                "specimenCheck": "attention",
                                "blackListCheck": "clear",
                                "dataIntegrity": "clear"
                            },
                            "clientValidation": {
                                "ageVerification": "clear",
                                "clientDataConsistency": "attention"
                            },
                            "consistencyAnalysis": {
                                "firstName": "clear",
                                "lastName": "clear",
                                "documentNumber": "clear",
                                "nationality": "not_processed",
                                "issuingDate": "not_processed",
                                "expirationDate": "clear",
                                "dob": "clear"
                            },
                            "extractedImages": [
                                {
                                    "type": "front_side",
                                    "index": 0,
                                    "data": "base64 string"
                                },
                                {
                                    "type": "extracted_face",
                                    "index": 2,
                                    "data": "base64 string"
                                },
                                {
                                    "type": "extracted_security_element",
                                    "index": 3,
                                    "data": "base64 string"
                                },
                                {
                                    "type": "extracted_signature",
                                    "index": 5,
                                    "data": "base64 string"
                                }
                            ],
                            "forensicAnalysis": {
                                "mrzVisualPlacement": "not_processed",
                                "securityElements": "clear",
                                "photoLocation": "clear",
                                "mrzClassification": "clear",
                                "documentLivenessCheck": "clear",
                                "tamperingDetected": "clear",
                                "breakdown": {
                                    "documentFrontLivenessScore": 96,
                                    "documentBackLivenessScore": 98
                                }
                            },
                            "formatAnalysis": {
                                "modelIdentification": "clear",
                                "countryModelValidity": "clear",
                                "documentModelValidity": "clear",
                                "photocopyDetected": "attention"
                            },
                            "frontAndBackAnalysis": {
                                "formatAnalysis": "not_processed",
                                "dataConsistency": "clear"
                            },
                            "securityAndPatternAnalysis": [
                                {
                                    "outcome": "clear",
                                    "narrative": "Barcode"
                                },
                                {
                                    "similarity": 94,
                                    "outcome": "clear",
                                    "narrative": "Clear",
                                    "index": 1,
                                    "actualImageData": ""
                                },
                                {
                                    "similarity": 94,
                                    "outcome": "clear",
                                    "narrative": "Clear",
                                    "index": 2,
                                    "actualImageData": "",
                                    "expectedImageData": ""
                                },
                                {
                                    "outcome": "clear",
                                    "narrative": "Clear"
                                }
                            ]
                        }
                    }
                }
            }
        ]
    }
}