> 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/biometric-verification/api-reference.md).

# API Reference

To initiate **Biometric Verification** using the VIDA Verify API, users must include both **imageFaceMatchVerification** and **imageLivenessVerification** in their list of operations and provide the required data for each process.

The API is designed to execute both operations concurrently. However, the outcome of **Image Face Match Verification** is directly dependent on the result of **Image Liveness Verification**. If the **Image Liveness Verification** fails—indicating the absence of a live person—there will be no response returned for the **Image Face Match Verification**. This ensures that facial matching is only performed when the authenticity of a live presence has been validated.

The overall success or failure of the **Biometric Verification** is, therefore, contingent upon passing the **Image Liveness Verification**. This layered verification process reinforces security by preventing unauthorized or spoofed attempts during identity authentication.

Additionally, this API can also perform **Blacklist Check**, given this service is enabled upon request. 

## Performing Liveness Check <a href="#api-description" id="api-description"></a>

{% hint style="info" %}
For details liveness check please refer to [here](broken://pages/7Fi3rRkbAZLqVadbAfka)
{% endhint %}

### API Description <a href="#api-description" id="api-description"></a>

`POST` `https://{vida-host}/api/v1/verify`

#### **Headers**

<table><thead><tr><th width="180.80078125">Name</th><th width="164.875">Type</th><th>Description</th></tr></thead><tbody><tr><td>Authentication*</td><td>String</td><td>Bearer &#x3C;Token></td></tr><tr><td>Content-Type</td><td></td><td>Format type of request body</td></tr></tbody></table>

#### Request Body

<table><thead><tr><th width="180.25390625">Name</th><th width="165.046875">Type</th><th>Description</th></tr></thead><tbody><tr><td>operations*</td><td>String</td><td>["imageLivenessVerification"]</td></tr><tr><td>payload*</td><td>String</td><td>{ "partnerTrxId": "random-uuid","groupId": "random-uuid",""faceImage": "Base64 encoded image" }</td></tr><tr><td>userConsent*</td><td>String</td><td>{ "userIP": "0.0.0.0", "country": "MYS", "obtained": true, "obtainedAt": "1680700959" }</td></tr></tbody></table>

### Sample Request and Response <a href="#sample-request-and-response" id="sample-request-and-response"></a>

**Request**

```
{
    "operations": ["imageLivenessVerification"],
    "payload": {
        "partnerTrxId": "{{$guid}}",
        "groupId": "{{$guid}}",
        "faceImage": ""
    },
    "userConsent": {
        "userIp": "226.80.211.232",
        "country": "MYS",
        "obtained": true,
        "obtainedAt": "1680700959"
    }
}
```

**Response**

```
{
  "transactionId": "unique transaction id generated to identify this transaction",
  "partnerTrxId": "partner transaction id submitted by customer in request",
  "groupId": "reference id to track complete KYC flow",
​
    "imageLivenessVerificationResult": {
        "data": {
            "code": 1043,
            "message": "Selfie photo is a live photo",
            "score": 0.066661
        }
    }
}
```

## Performing Biometric Verification

### API Description <a href="#api-description" id="api-description"></a>

`POST` `https://{vida-host}/api/v1/verify`

**Headers**

<table><thead><tr><th width="180.34765625">Name</th><th width="165.390625">Type</th><th>Description</th></tr></thead><tbody><tr><td>Authentication*</td><td>String</td><td>Bearer &#x3C;Token></td></tr><tr><td>Content-Type</td><td></td><td>Format type of request body</td></tr></tbody></table>

**Request Body**

<table><thead><tr><th width="179.9765625">Name</th><th width="165.375">Type</th><th>Description</th></tr></thead><tbody><tr><td>operations*</td><td>String</td><td>["imageFaceMatchVerification","imageLivenessVerification"]</td></tr><tr><td>payload*</td><td>String</td><td>{ "partnerTrxId": "random-uuid","groupId": "random-uuid",""faceImage": "Base64 encoded image","croppedFaceImage"or"idFrontSideImage": "Encoded Base64 id card" } <a href="https://app.gitbook.com/o/HFo4Mq4hPbfFvhTREpfY/s/g6YEYlQLUbaNxLL3Aiz4/myservice-api/api-reference/perform-imageliveness-and-imagefacematch#sample-request-and-response">Sample Request</a>​</td></tr><tr><td>userConsent*</td><td>String</td><td>{ "userIP": "0.0.0.0", "country": "MYS", "obtained": true, "obtainedAt": "1680700959" }</td></tr></tbody></table>

### Sample Request and Response <a href="#sample-request-and-response" id="sample-request-and-response"></a>

#### Request <a href="#request" id="request"></a>

```
{
  "operations": [
    "imageFaceMatchVerification",
    "imageLivenessVerification"
  ],
  "payload": {
    "partnerTrxId": "random-uuid",
    "groupId": "random-uuid",
    "faceImage": "Base64 encoded image",
    "idFrontSideImage": "Encoded Base64 Id card"
  },
  "userConsent": {
    "userIP": "0.0.0.0",
    "country": "MYS",
    "obtained": true,
    "obtainedAt": "1680700959"
  }
}
```

**Response**

HTTP Status Code: `200`

```
{
  "transactionId": "unique transaction id generated to identify this transaction",
  "partnerTrxId": "partner transaction id submitted by customer in request",
  "groupId": "reference id to track complete KYC flow",
​
   "imageFaceMatchVerificationResult": {
        "data": {
            "code": 1042,
            "message": "Selfie photo matches with reference photo",
            "score": 0.992796
        }
    },
    "imageLivenessVerificationResult": {
        "data": {
            "code": 1043,
            "message": "Selfie photo is a live photo",
            "score": 0.066661
        }
    }
}
```

## Performing Blacklist Check <a href="#api-description" id="api-description"></a>

### Purpose <a href="#api-description" id="api-description"></a>

To prevent onboarding or verification of users whose facial images appear in a blacklist database.\
The check runs before the `faceMatch` operation, and if a match is found, the `faceMatch` step will be skipped. Blacklist Check can be done as part of Liveness Check and also standalone Blacklist Check [here](broken://pages/veR3xFGLNVSrS83GHwAt).&#x20;

<figure><img src="/files/bKzKpafrXwmDp1kin0ft" alt="" width="375"><figcaption></figcaption></figure>

### Flow <a href="#api-description" id="api-description"></a>

1. Check if Blacklist Check is enabled for product, if yes then perform this check
2. If the blacklist check fails (face found in blacklist), the system will return an error response with appropriate code and message.
3. If there is no blacklist image found, the system will return the success response.&#x20;

### API Description <a href="#api-description" id="api-description"></a>

`POST` `https://{vida-host}/api/v1/verify`

HTTP Status Code : `200`&#x20;

<details>

<summary>Success <strong>JSON Response for Face Match with No Blacklist Found</strong></summary>

```json
{
  "transactionId": "unique transaction id generated to identify this transaction",
  "partnerTrxId": "partner transaction id submitted by customer in request",
  "groupId": "reference id to track complete KYC flow",
​
   "imageFaceMatchVerificationResult": {
        "data": {
            "code": 1042,
            "message": "Selfie photo matches with reference photo",
            "score": 0.992796
        }
    },
    "imageLivenessVerificationResult": {
        "data": {
            "code": 1043,
            "message": "Selfie photo is a live photo",
            "score": 0.066661
        }
    },
    "blacklistCheckResult": {
        "faceReferences": []
    }
}
```

</details>

<details>

<summary>Success <strong>JSON Response for Face Match With Blacklist Warning</strong> </summary>

```json
{
  "transactionId": "unique transaction id generated to identify this transaction",
  "partnerTrxId": "partner transaction id submitted by customer in request",
  "groupId": "reference id to track complete KYC flow",
​    "warnings": [
        {
            "message": "Image is blacklisted.",
            "code": 10501,
            "operations": [
                "imageFaceMatchVerification"
            ]
        }
    ],
   "imageFaceMatchVerificationResult": {
        "data": {
            "code": 1042,
            "message": "Selfie photo matches with reference photo",
            "score": 0.992796
        }
    },
    "imageLivenessVerificationResult": {
        "data": {
            "code": 1043,
            "message": "Selfie photo is a live photo",
            "score": 0.066661
        }
    },
    "blacklistCheckResult": {
        "faceReferences": [
            {
                "faceId": "f4640eae-5e10-4405-99ea-051826756fb2",
                "matchScore": 1.0
            }
        ]
    }
}

```

</details>

HTTP Status Code : `400`

<details>

<summary>Error <strong>JSON Response for Front Side and Back Side - With Error</strong> </summary>

```json
{
  "transactionId": "unique transaction id generated to identify this transaction",
  "partnerTrxId": "partner transaction id submitted by customer in request",
  "groupId": "reference id to track complete KYC flow",
​   "errors": [
        {
            "message": "Verification failed: Image is blacklisted.",
            "code": 5801,
            "operations": [
                "imageFaceMatchVerification"
            ]
        }
    ], 
    "imageLivenessVerificationResult": {
        "data": {
            "code": 1043,
            "message": "Selfie photo is a live photo",
            "score": 0.066661
        }
    },
     "blacklistCheckResult": {
        "faceReferences": [
            {
                "faceId": "bdc41279-d391-4fc9-8d94-972661fae720",
                "matchScore": 1.0
            }
        ]
    }
}

```

</details>