# Identity Check

## Run an identity check

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

This check can only be performed on a [client](https://docs.complycube.com/documentation/api-reference/core-resources/clients) of type `person`. 

The `documentId` provided must have associated image attachments that adhere to our [image specifications](https://docs.complycube.com/documentation/api-reference/document-check#image-specifications). 

[Learn more about Identity Checks](https://app.gitbook.com/s/KyFKMqftsmT6qln9zo5y/biometric-and-liveness-verification/identity-check).

{% hint style="info" %}
We will use the **front side** of the document for the Identity Check.
{% endhint %}

## Check request

<table><thead><tr><th width="337.91390728476824">Attribute</th><th width="108.33333333333331">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>identity_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>livePhotoId</code></td><td>string</td><td>The ID of the live photo. (<strong>Required</strong>)</td></tr><tr><td><code>options</code></td><td>string</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  <a href="#the-options-object" id="the-options-object"></a>

<table><thead><tr><th width="336.3333333333333">Attribute</th><th width="110">Type</th><th>Description</th></tr></thead><tbody><tr><td><code>enableEnrolledFaces</code></td><td>boolean</td><td>Determines whether enrolled face matching is enabled. When this attribute is not provided, it will <strong>default to true</strong>.</td></tr><tr><td><code>enableSpecimenMatching</code></td><td>boolean</td><td>Determines whether specimen matching is enabled. When this attribute is not provided, it will <strong>default to true</strong>.</td></tr><tr><td><code>enableVpnDetection</code></td><td>boolean</td><td>Determines whether VPN detection is enabled. When this attribute is not provided, it will <strong>default to true</strong>.</td></tr></tbody></table>

### Example request

#### 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",
          "livePhotoId":"LIVE_PHOTO_ID",
          "documentId":"DOCUMENT_ID",
          "type": "identity_check"
        }'
```

{% 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", {
        livePhotoId: "LIVE_PHOTO_ID",
        documentId: "DOCUMENT_ID",
        type: "identity_check"
});
```

{% endtab %}

{% tab title="Python" %}

```python
from complycube import ComplyCubeClient

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

check = cc_api.check.create(
    'CLIENT_ID', 
    'identity_check', 
    livePhotoId='LIVE_PHOTO_ID',
    documentId='DOCUMENT_ID'
)
```

{% endtab %}

{% tab title="PHP" %}

```php
use ComplyCube\ComplyCubeClient;

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

$result = $ccapi->checks()->create(
    'CLIENT_ID',
    [
        'type' => 'identity_check',
        'livePhotoId' => 'LIVE_PHOTO_ID',
        '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",
  documentId = "DOCUMENT_ID",
  livePhotoId = "LIVE_PHOTO_ID",
  type = "identity_check"
};

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",
          "livePhotoId":"LIVE_PHOTO_ID",
          "documentId":"DOCUMENT_ID",
          "type": "identity_check"
          "options":{
               "enableEnrolledFaces": false,
               "enableSpecimenMatching": false,
               "enableVpnDetection": 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", {
    livePhotoId: "LIVE_PHOTO_ID",
    documentId: "DOCUMENT_ID",
    type: "identity_check",
    options: {
        enableEnrolledFaces: false,
        enableSpecimenMatching: false,
        enableVpnDetection: false
    }
});
```

{% endtab %}

{% tab title="Python" %}

```python
from complycube import ComplyCubeClient

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

options = {
    enableEnrolledFaces: false,
    enableSpecimenMatching: false,
    enableVpnDetection: false,
}

check = cc_api.check.create(
    "CLIENT_ID",
    "identity_check",
    livePhotoId="LIVE_PHOTO_ID",
    documentId="DOCUMENT_ID",
    options=options,
)

```

{% endtab %}

{% tab title="PHP" %}

```php
use ComplyCube\ComplyCubeClient;

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

$result = $ccapi->checks()->create(
    'CLIENT_ID',
    [
        'type' => 'identity_check',
        'livePhotoId' => 'LIVE_PHOTO_ID',
        'documentId' => 'DOCUMENT_ID',
        'options' => [
               'enableEnrolledFaces' => false,
               'enableSpecimenMatching' => false,
               'enableVpnDetection' => false
              ]
    ]
);
```

{% 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",
  documentId = "DOCUMENT_ID",
  livePhotoId = "LIVE_PHOTO_ID",
  type = "identity_check"
};

checkRequest.options = new CheckRequestOptions {
  enableEnrolledFaces = false,
  enableSpecimenMatching = false,
  enableVpnDetection = false,
};

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 conducted returned a successful result, and hence the identity is authentic.
2. `attention`: Indicates at least one of the analysis results requires attention.

### Breakdown

The breakdown comprises the following objects:

#### `faceAnalysis` object

&#x20;The facial analysis results. It has the following constituents:

* `faceDetection`: Indicates whether a face is detected and that number of faces detected on the ID and live photo are valid.
* `facialSimilarity`: Indicates whether the faces on the live photo and document belong to the same person.
* `previouslyEnrolledFace`: Indicates whether the face on the live photo has been previously enrolled as a different client.
* `breakdown`: Breakdown related to facial analysis.
  * `facialSimilarityScore`: Indicates the similarity level of whether two faces belong to the same person. The score will be 100 for a perfect match.
  * `enrolledFacesMatches`: If a face is deemed to have been enrolled previously, this will contain an array of objects that contain the following:
    * `clientId`: The unique identifier for the matching client.
    * `entityName`: The client's full name.&#x20;
    * `livePhotoId`: The unique identifier for the matching live photo.
    * `liveVideoId`: The unique identifier for the matching live video. Either a **liveVideoId** or **livePhotoId** will exist in the object, not both.&#x20;
    * `facialSimilarityScore`: The similarity level of the client's face against the live photo associated with the check.

#### `authenticityAnalysis` object

&#x20;The facial analysis results. It has the following constituents:

* `spoofedImageAnalysis`: Indicates whether the images are spoofed, copied from the internet, or are known blacklisted images.
* `livenessCheck`: Indicates if the live photo is genuine and not a photo-of-an-image or photo-of-a-screen.
* `breakdown`: Breakdown related to authenticity analysis.
  * `specimenCheckMatches`: If an image is deemed copied from the internet, this will contain an array of URLs pointing to the image.
  * `livenessCheckScore`: Indicates the liveness score of the live photo. The score will be 100 when it is assumed to be authentic.

#### `integrityAnalysis` object

&#x20;The integrity analysis results. It has the following constituents:

* `faceDetection`: Indicates whether the images contained the expected number of faces.
* `vpnDetected`: Indicates whether the client was using a Virtual Private Network (VPN) when conducting the check.

## Sample Response

```javascript
{
   "id": "5e94b88a01bce00008c86f06",
   "entityName": "John Doe",
   "type": "identity_check",
   "clientId": "5e94b75d01bce00008c86f02",
   "documentId": "5e94b87b01bce00008c86f03",
   "livePhotoId": "5e94b88901bce00008c86f05",
   "status": "complete",
   "result": {
      "outcome": "clear",
      "breakdown": {
         "faceAnalysis": {
            "faceDetection": "clear",
            "facialSimilarity": "clear",
            "previouslyEnrolledFace": "clear",
            "breakdown": {
               "facialSimilarityScore": 100
            }
         },
         "authenticityAnalysis": {
            "spoofedImageAnalysis": "clear",
            "livenessCheck": "clear",
            "breakdown": {
               "livenessCheckScore": 100
            }
         },
         "integrityAnalysis": {
            "faceDetection": "clear",
            "vpnDetected": "clear"
         }
      }
   },
   "createdAt": "2020-01-04T17:25:21.116Z",
   "updatedAt": "2020-01-04T17:25:21.116Z"
}
```