> For the complete documentation index, see [llms.txt](https://docs.vida.id/identity-stack/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.vida.id/identity-stack/verify/liveness/integration/api/api-reference/liveness-check.md).

# Liveness Check

## Liveness API

<mark style="color:green;">`POST`</mark> `https://{vida.host}/biometrics/v2/services/face/liveliness`

#### Headers

| Name                                            | Type             | Description                                                                                              |
| ----------------------------------------------- | ---------------- | -------------------------------------------------------------------------------------------------------- |
| Authorization<mark style="color:red;">\*</mark> |                  | <p>OAuth access token. </p><p>Get the token by calling the</p><p><strong>Authentication</strong> API</p> |
| Content-Type<mark style="color:red;">\*</mark>  | application/json | Format type of request body                                                                              |

#### Request Body

<table><thead><tr><th width="262.3203125">Name</th><th width="116.7421875">Type</th><th>Description</th></tr></thead><tbody><tr><td>image<mark style="color:red;">*</mark></td><td>String</td><td>Data URI scheme, Base64 encoded image.</td></tr><tr><td>partnerTrxId<mark style="color:red;">*</mark></td><td>String</td><td>A partner can optionally send a transaction id to co-relate their transaction with VIDA transaction. However, it is an optional parameter and is maintained by the partner.</td></tr><tr><td>imgManipulationCheckEnabled</td><td>boolean</td><td>Enable this option to identify morph patterns commonly present in photoshopped images, generated swapped selfie images, and deep fakes.</td></tr></tbody></table>

#### API Response

### Liveness Detection Successful

HTTP Status Code: `200`

<details>

<summary>JSON Response</summary>

{% code title="The system detected a higher confidence of live selfie when the liveness score < 0.95." %}

```json
{
   "data": {
      "code": 1043,
      "message": "Selfie photo is a live photo",
      "score": "0.001102",
      "imgManipulationScore": "0.098010", //Available only when imgManipulation is enabled
      "transactionId": "f373342c-77f8-406e-95ca-1a9744369b28"
   }
} 
```

{% endcode %}

</details>

The success response in live selfie will consist of:&#x20;

* score&#x20;
* transactionId.&#x20;

The liveness score ranges from 0 to 1. The score of 0 (zero) represents maximum liveness, and the score of 1 represents minimum liveness of the selfie. The default threshold is a 0.95 score.

### Liveness Score below the Threshold

HTTP Status Code: `200`

<details>

<summary>JSON Response</summary>

```json
{
   "data": {
      "code": 1041,
      "message": "Photo liveness score is below the threshold",
      "score": "0.950057",
      "imgManipulationScore": "0.997923", //Available only when imgManipulation is enabled
      "transactionId": "b3be6fd3-b507-4bc5-9e79-e487ae869624"
   }
}
```

</details>

The system detected a higher confidence of spoofed or hacked selfie when the liveness score >= 0.95.&#x20;

The success response in spoof or hacked selfie will consist of:&#x20;

* score
* transactionId&#x20;

The liveness score ranges from 0 to 1. The score of 0 (zero) represents maximum liveness and the score of 1 represents minimum liveness of the selfie. The default threshold is a 0.95 score.

### Face Occluded

HTTP Status Code: `400`

{% hint style="info" %}
**Recommendation** : The partner must ensure there is no occluded object when capturing the selfie.
{% endhint %}

<details>

<summary>JSON Response</summary>

```json
{
   "errors": [
      {
         "code": 1051,
         "title": "detect un-standardized image quality",
         "detail": "Face Occluded"
      }
   ],
 "transactionId": "ea6385be-7d24-459c-a526-e34f099afdd9"
}
```

</details>

The face in the selfie is occluded by an object.&#x20;

### Face Too Small

HTTP Status Code: `400`

{% hint style="info" %}
**Recommendation**: The partner must capture the face size area greater than 50x50 pixels.
{% endhint %}

<details>

<summary>JSON Response</summary>

```json
{
   "errors": [
      {
         "code": 1052,
         "title": "detect un-standardized image quality",
         "detail": "Face too small"
      }
   ],
    "transactionId": "3b893cc2-e18f-47eb-a44e-80e7d879fdaa"
}
```

</details>

The face size area is smaller than 50 x 50 pixels.&#x20;

### Image quality low

HTTP Status Code: `400`

{% hint style="info" %}
**Recommendation**: The partner needs to ensure the image input is in good quality condition.
{% endhint %}

<details>

<summary>JSON Response</summary>

```json
{
   "errors": [
      {
         "code": 1053,
         "title": "detect un-standardized image quality",
         "detail": "Image quality low"
      }
   ],
    "transactionId": "3b893cc2-e18f-47eb-a44e-80e7d879fdaa"
}
```

</details>

The system captures the possibility of broken image, corrupted image, or low quality.&#x20;

### Multiple faces detected

HTTP Status Code: `400`

{% hint style="info" %}
**Recommendation**: The partner needs to ensure that only one face is in the frame.
{% endhint %}

<details>

<summary>JSON Response</summary>

```json
{
   "errors": [
      {
         "code": 1054,
         "title": "detect un-standardized image quality"",
         "detail": "More than one face"
      }
   ],
    "transactionId": "3b893cc2-e18f-47eb-a44e-80e7d879fdaa"
}
```

</details>

Multiple faces are detected in the frame.&#x20;

### No face detected

HTTP Status Code: `400`

{% hint style="info" %}
**Recommendation**: The partner needs to ensure at least one face is present in the frame.
{% endhint %}

<details>

<summary>JSON <strong>Response</strong></summary>

```json
{
   "errors": [
      {
         "code": 1055,
         "title": "detect un-standardized image quality",
         "detail": "No face detected"
      }
   ],
    "transactionId": "3b893cc2-e18f-47eb-a44e-80e7d879fdaa"
}
```

</details>

No face object found in the image frame.&#x20;

### Unnatural Colour Detected

HTTP Status Code: `400`

{% hint style="info" %}
**Recommendation**: The partner needs to ensure the selfie should be clean and undamaged.
{% endhint %}

<details>

<summary><strong>JSON Response</strong></summary>

```json
{
   "errors": [
      {
         "code": 1063,
         "title": "Image Quality Is Below Threshold",
         "detail": "Unnatural colour"
      }
   ],
    "transactionId": "3b893cc2-e18f-47eb-a44e-80e7d879fdaa"
}
```

</details>

Damaged image or saturated image is detected.

### Under Exposure Detected

HTTP Status Code: `400`

{% hint style="info" %}
**Recommendation**: The partner needs to ensure the selfie should be well-lit and properly exposed.
{% endhint %}

<details>

<summary><strong>JSON Response</strong></summary>

```json
{
   "errors": [
      {
         "code": 1074,
         "title": "Image Quality Is Below Threshold",
         "detail": "Under Exposure"
      }
   ],
    "transactionId": "3b893cc2-e18f-47eb-a44e-80e7d879fdaa"
}
```

</details>

A low lighting selfie is detected.

### Over Exposure Detected

HTTP Status Code: `400`

{% hint style="info" %}
**Recommendation**: The partner needs to ensure the selfie should be properly exposed with no blown-out highlight.
{% endhint %}

<details>

<summary>JSON Response</summary>

```json
{
   "errors": [
      {
         "code": 1075,
         "title": "Image Quality Is Below Threshold",
         "detail": "Over Exposure"
      }
   ],
    "transactionId": "3b893cc2-e18f-47eb-a44e-80e7d879fdaa"
}
```

</details>

Overexposure or blown-out highlights in a selfie are detected.

### Blurry Image Detected

HTTP Status Code: `400`

{% hint style="info" %}
**Recommendation**: The partner needs to ensure the selfie should be sharp and in focus.
{% endhint %}

<details>

<summary>JSON Response</summary>

```json
{
   "errors": [
      {
         "code": 1076,
         "title": "Image Quality Is Below Threshold",
         "detail": "Image is blur"
      }
   ],
    "transactionId": "3b893cc2-e18f-47eb-a44e-80e7d879fdaa"
}
```

</details>

Blurry conditions or defocused face in a selfie are detected.

## Multiple Error Example

The error response format in case of multiple error.

{% hint style="info" %}
**Recommendation**: The partner needs to ensure all the errors are addressed.
{% endhint %}

HTTP Status Code: `400`

### Over Exposure, Image is Blur and Unnatural color&#x20;

<details>

<summary>JSON Response</summary>

```json
{
    "errors": [
        {
            "code": 1075,
            "title": "Image Quality Is Below Threshold",
            "detail": "Over Exposure"
        },
        {
            "code": 1076,
            "title": "Image Quality Is Below Threshold",
            "detail": "Image Is Blur"
        },
        {
            "code": 1063,
            "title": "Image Quality Is Below Threshold",
            "detail": "Unnatural colour"
        }
    ],
    "transactionId": "3392154b-fce8-49ea-92cb-75272b7ea016"
}

```

</details>

### Unnatural Color and Under Exposure

<details>

<summary>JSON Response</summary>

```json
{
    "errors": [
        {
            "code": 1063,
            "title": "Image Quality Is Below Threshold",
            "detail": "Unnatural colour"
        },
        {
            "code": 1074,
            "title": "Image Quality Is Below Threshold",
            "detail": "Under Exposure"
        }
    ],
    "transactionId": "9e9f0a0e-ef36-4579-a844-240debf1c235"
}
```

</details>

### Unnatural Color and Blur Image

<details>

<summary>JSON Response</summary>

```json
{
    "errors": [
        {
            "code": 1076,
            "title": "Image Quality Is Below Threshold",
            "detail": "Image Is Blur"
        },
        {
            "code": 1063,
            "title": "Image Quality Is Below Threshold",
            "detail": "Unnatural colour"
        }
    ],
    "transactionId": "9488b3d0-530c-42e3-9191-5bf63f1e63fe"
}
```

</details>