---
title: "Verify Face"
method: POST
path: "/v1/face/verify"
tags: ["Face"]
---

# Verify Face

`POST /v1/face/verify`

## Request

- Base URL: `https://api.verihubs.com`
- URL: `https://api.verihubs.com/v1/face/verify`
- Auth: none declared. Required headers: `App-ID`, `API-Key`

This method helps you verify face with specific image
<br>
You will receive a response consists of message and an error code if the request fails to process. The following is a list of error codes.
<br>

| Error Status                                 | Error code                    | Description                                  |
| -----------------------------|:---------------------------------------------|:---------------------------------------------|
| 200 | FAIL_ON_1                      | fail on liveness                          |
| 200 | FAIL_ON_2                      | fail on attribute                         |
| 200 | FAIL_ON_3                      | fail on liveness and attribute            |
| 200 | FAIL_ON_4                      | fail on quality                           |
| 200 | FAIL_ON_5                      | fail on liveness and quality              |
| 200 | FAIL_ON_6                      | fail on attribute and quality             |
| 200 | FAIL_ON_7                      | fail on liveness, attribute, and quality  |
|200   | FAIL_ON_8                   | fail on number of face (nface)  |
|200   | FAIL_ON_9                   | fail on  number of face (nface) and liveness  |
|200   | FAIL_ON_10                   | fail on  number of face (nface) and attribute |
|200   | FAIL_ON_11                  | fail on  number of face (nface), attribute, and liveness  |
|200   | FAIL_ON_12                   | fail on  number of face (nface) and quality|
|200   | FAIL_ON_13                  | fail on  number of face (nface), quality, and liveness |
|200   | FAIL_ON_14                 | fail on  number of face (nface), quality, and attribute |
|200   | FAIL_ON_15                 | fail on  number of face (nface), quality, attribute, and liveness |
|200   | FAIL_ON_16                  | fail on similarity status |
| 400 | INVALID_PAYLOAD                | no value in payload or empty string more than 1  |
| 400 |INVALID_PAYLOAD_IMAGE_MISSING  | invalid payload image not a standard b64/url or image empty string |
| 400 | INVALID_PAYLOAD_IMAGE_SIZE    | invalid payload image size too large |
| 400 | MISSING_PAYLOAD_IMAGE         |  missing payload image                       |
| 400 | MISSING_PAYLOAD_SUBJECT_ID       |  missing payload subject id                       |
| 400 | INVALID_PAYLOAD_IMAGE_TIMEOUT  | timeout getting image from url in 15 seconds                |
| 400 | INVALID_PAYLOAD_IMAGE_FORMAT   | image unable to be decoded/got from url OR invalid image extension |
| 400 | FACE_NOT_DETECTED              | face not detected from image              |
| 400 | INVALID_PAYLOAD_SUBJECT_ID    | subject id not valid / subject id is not found |
| 400 | INVALID_PAYLOAD_SUBJECT_ID_MISSING | subject_id payload is empty / null |
| 400 | INVALID_PAYLOAD_QUALITY_VALIDATION_DEPENDENCY  | is_quality must be true if validate_quality true |
| 400 | INVALID_PAYLOAD_ATTRIBUTE_VALIDATION_DEPENDENCY  | is_attribute must be true if validate_attribute true |
| 400 | INVALID_PAYLOAD_LIVENESS_VALIDATION_DEPENDENCY  | is_liveness must be true if validate_liveness true |
| 400 | INVALID_PAYLOAD_THRESHOLD_MISSING  | threshold must be basic/moderate/high                 |
| 403 | INSUFFICIENT_QUOTA_VERIFY     | usage reach it quota limit for verify (only appears on testing mode)|
| 403 | INSUFFICIENT_QUOTA_LIVENESS   | usage reach it quota limit for liveness (only appears on testing mode)  |
| 500 | INTERNAL_SERVER_ERROR         | internal server error |

## Headers

- `App-ID` string, required
- `API-Key` string, required

## Request body

- VerifyFace
  - `image` string, required: A base64 or URL image file.
  - `subject_id` string, required: Subject ID.
  - `is_quality` boolean: A flag to determine whether Image Quality (blur, dark, grayscale) will be computed and return as result
  - `is_attribute` boolean: A flag to determine whether Image Attribute (sunglasses, mask, veil, hat) will be detected and return as result
  - `is_liveness` boolean: A flag to determine whether Passive Liveness will be computed and return as result. When is_liveness is set to true, it is best that validate_quality is set to true, as liveness is influenced by Quality.
  - `validate_quality` boolean: Determines whether Quality validation will be executed. The validation consists of checking blur and dark with threshold, and also checking whether the image is a black & white image (grayscale is true).
  - `validate_attribute` boolean: Determines whether Attribute validation will be executed. The validation consists of checking whether sunglasses or mask is detected in the input image.
  - `validate_liveness` boolean: Determines whether Liveness validation will be executed. The validation checks whether input image is live / spoof.
  - `threshold` string: Determines which threshold level will be used. The threshold either basic/moderate/high
  - `validate_nface` boolean: Determines whether the number of faces validation will be executed. The validation checks whether the input image consists of more than one face. (Will be released at 1 Sep 2023)

## Response `200`

Successful Response

- ResponseVerifyFace
  - `status_code` string: Status Code
  - `message` string, required: Message
  - `subject_id` string: Subject ID
  - `session_id` string: unique id to represent transaction record
  - `attributes` object
    - `sunglasses_on` boolean
    - `mask_on` boolean
    - `veil_on` boolean
    - `hat_on` boolean
  - `liveness` object: Liveness attribute
    - `status` boolean
    - `probability` string
  - `image_quality` object: Shows quality of image
    - `blur` boolean
    - `dark` boolean
    - `grayscale` boolean
  - `rotation` integer: Shows how many rotations need to be done to detect face in image
  - `bounding_box` object: Shows result bounding box
    - `TopLeftX` string
    - `TopLeftY` string
    - `BottomRightX` string
    - `BottomRightY` string
    - `Width` string
    - `Height` string
  - `face_landmark` object: Shows result of face landmark
    - `LeftEyeX` string
    - `LeftEyeY` string
    - `RightEyeX` string
    - `RightEyeY` string
    - `NoseX` string
    - `NoseY` string
    - `MouthLeftX` string
    - `MouthLeftY` string
    - `MouthRightX` string
    - `MouthRightY` string
  - `nface` integer: Shows how many faces are detected in the input image.
  - `similarity_status` boolean: Shows similarity result
  - `timestamp` number: Shows time which face verified successfully

## Other responses

- `400`: Bad Request
- `401`: Unauthorized
- `500`: Internal Server Error

---

[API](https://skmtc.dev/verihubs/apis/ai-api-documentation.md) - [All operations](https://skmtc.dev/verihubs/apis/ai-api-documentation/llms.txt) - [OpenAPI document](https://skmtc.dev/verihubs/apis/ai-api-documentation/revisions/9313db607e15?raw)