# Document Check

## Run a document check

To run a Document Check, you must [create a check ](https://docs.complycube.com/documentation/api-reference/core-resources/checks/create-a-check)with the `type` set to `document_check`

The provided document must have an `issuingCountry` and associated image attachments that adhere to our [image specifications](#image-specifications). 

The **front side** of the document will always be required. For certain [document types](https://app.gitbook.com/s/KyFKMqftsmT6qln9zo5y/identity-verification/document-check/document-sides-per-type), you should also provide the **back side**.

[Learn about Document Checks](https://app.gitbook.com/s/KyFKMqftsmT6qln9zo5y/identity-verification/document-check).

{% hint style="warning" %}
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.
{% endhint %}

## 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

<table><thead><tr><th width="267.66147859922177">Attribute</th><th width="129">Type</th><th>Description</th></tr></thead><tbody><tr><td><code>clientId</code></td><td>string</td><td>The ID of the client associated with this check. (<strong>Required</strong>)</td></tr><tr><td><code>type</code></td><td>string</td><td>This must be set to <code>document_check</code>. (<strong>Required</strong>)</td></tr><tr><td><code>documentId</code></td><td>string</td><td>The ID of the document. (<strong>Required</strong>)</td></tr><tr><td><code>options</code></td><td>object</td><td>The optional settings for the check. Also, see the <a href="#the-options-object">options</a> object below. (<em>Optional</em>)</td></tr></tbody></table>

### The `options` object&#x20;

<table><thead><tr><th width="270.2809747140587">Attribute</th><th width="125.86814292903878">Type</th><th>Description</th></tr></thead><tbody><tr><td><code>analysisCoverage</code></td><td><p>array[string]</p><p></p><p></p></td><td><p>The types of analysis to conduct as part of a document check. Valid values include:</p><ol><li><code>consistency_analysis</code></li><li><code>forensic_analysis</code></li><li><code>content_analysis</code></li><li><code>format_analysis</code></li><li><code>front_back_analysis</code></li><li><code>mrz_analysis</code></li></ol><p>When this attribute is not provided, we will conduct all analysis types.</p></td></tr><tr><td><code>minimumPermittedAge</code></td><td><p>number</p><p></p><p></p></td><td>The minimum acceptable age before your client ID is flagged. When this attribute is not provided, we will default the <strong>minimum age to 18</strong>.</td></tr><tr><td><code>clientDataValidation</code></td><td>boolean</td><td>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 <strong>default to false</strong>.</td></tr></tbody></table>

## Example requests

#### Simple request

{% tabs %}
{% tab title="cURL" %}

```bash
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"
        }'
```

{% endtab %}

{% tab title="Node.js" %}

```javascript
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"
});
```

{% endtab %}

{% tab title="Python" %}

```python
from complycube import ComplyCubeClient

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

check = cc_api.checks.create(
    'CLIENT_ID',
    'document_check', 
    documentId='DOCUMENT_ID'
)
```

{% endtab %}

{% tab title="PHP" %}

```php
use ComplyCube\ComplyCubeClient;

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

$result = $ccapi->checks()->create(
    'CLIENT_ID',
    [
        'type' => 'document_check',
        'documentId' => 'DOCUMENT_ID'
    ]
);
```

{% endtab %}

{% tab title=".NET" %}

```csharp
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);
```

{% endtab %}
{% endtabs %}

#### Request with optional attributes

{% tabs %}
{% tab title="cURL" %}

```bash
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
               }
        }'
```

{% endtab %}

{% tab title="Node.js" %}

```javascript
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
    }
});
```

{% endtab %}

{% tab title="Python" %}

```python
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)
```

{% endtab %}

{% tab title="PHP" %}

```php
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);
```

{% endtab %}

{% tab title=".NET" %}

```csharp
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);
```

{% endtab %}
{% endtabs %}

## 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. `clear`: Indicates every [analysis type](https://docs.complycube.com/documentation/checks/document-check#analysis-performed) conducted returned a successful result, and hence the document is authentic.
2. `attention`: Indicates at least one of the analysis results requires attention.
3. `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.&#x20;

### Breakdown

The breakdown comprises the following objects:

#### `extractedData` object

The data extracted using [Optical Character Recognition (OCR)](https://en.wikipedia.org/wiki/Optical_character_recognition). It has the following constituents:

* `documentDetails`: Data relating to the document.

  * `documentType`: The detected document type. Values include:&#x20;

    * `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.

  * `issuingCountry`: The issuing country of the document. This will be the [two-letter country ISO code](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2).

  * `expirationDate`: The expiry date of the document. This will be a [structured date](https://docs.complycube.com/documentation/api-reference/core-resources/checks#structured-date-format).

  * `documentNumber`: The document number.

  * `personalNumber`: The personal number, if available.

  * `issuingDate`: The issuing date of the document. This will be a [structured date](https://docs.complycube.com/documentation/api-reference/core-resources/checks#structured-date-format).

  * `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.

  * `mrz` : The [Machine Readable Zone (MRZ)](https://en.wikipedia.org/wiki/Machine-readable_passport), 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`

* `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.
  * `dob`: The date of birth. This will be a [structured date](https://docs.complycube.com/documentation/api-reference/core-resources/checks#structured-date-format).
  * `age`: The age of the document holder. This will be a `number`.
  * `birthPlace`: The birthplace.
  * `nationality`: The nationality. This will be the [two-letter country ISO code](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2).
  * `taxIdentificationNumber`: The Tax Identification Number (TIN).
  * `healthInsuranceNumber`: The health insurance number.
  * `gender`:  The gender. Values include:&#x20;
    * `male`
    * `female`
    * `other`<br>

* `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.&#x20;
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.&#x20;
* `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.&#x20;
* `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.&#x20;
* `lastName`: Indicates whether the last name on the document and MRZ are consistent.&#x20;
* `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.&#x20;
* `personalNumber`: Indicates whether the personal number on the document and MRZ are consistent.&#x20;
* `issuingDate`: Indicates whether issuing date on the document and MRZ are consistent.&#x20;
* `expirationDate`: Indicates whether the expiry date on the document and MRZ are consistent.&#x20;

#### `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

```json
{
  "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"
}
```