---
title: "Compare Face"
method: POST
path: "/v1/face/compare"
tags: ["Face"]
---
# Compare Face
`POST /v1/face/compare`
## Request
- Base URL: `https://api.verihubs.com`
- URL: `https://api.verihubs.com/v1/face/compare`
- Auth: none declared. Required headers: `App-ID`, `API-Key`
This method helps you to compare face between 2 images
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.
| 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_1_MISSING | invalid payload image 1 not a standard b64/url or image empty string |
| 400 | INVALID_PAYLOAD_IMAGE_2_MISSING | invalid payload image 2 not a standard b64/url or image empty string |
| 400 | INVALID_PAYLOAD_IMAGE_1_SIZE | invalid payload image 1 size too large |
| 400 | INVALID_PAYLOAD_IMAGE_2_SIZE | invalid payload image 2 size too large |
| 400 | MISSING_PAYLOAD_IMAGE_1 | missing payload image 1 |
| 400 | MISSING_PAYLOAD_IMAGE_2 | missing payload image 2 |
| 400 | INVALID_PAYLOAD_IMAGE_1_TIMEOUT | timeout getting image 1 from url in 15 seconds |
| 400 | INVALID_PAYLOAD_IMAGE_2_TIMEOUT | timeout getting image 2 from url in 15 seconds |
| 400 | INVALID_PAYLOAD_IMAGE_1_FORMAT | image unable to be decoded/got from url OR invalid image 1 extension |
| 400 | INVALID_PAYLOAD_IMAGE_2_FORMAT | image unable to be decoded/got from url OR invalid image 2 extension |
| 400 | FACE_NOT_DETECTED | face not detected from image |
| 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_COMPARE | usage reach it quota limit for compare (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
- CompareFace
- `image_1` string, required: An image file, base64 or URL of the first person.
- `image_2` string, required: An image file, base64 or URL of the second person.
- `is_quality` boolean: A flag to determine whether Image Quality (blur, dark, grayscale) will be computed and return as result. Quality will be computed for both image_1 and image_2 when set as true
- `is_attribute` boolean: A flag to determine whether Image Attribute (sunglasses, mask, veil, hat) will be detected and return as result. Attribute will be computed for both image_1 and image_2 when set as true
- `is_liveness` boolean: A flag to determine whether Passive Liveness will be computed and return as result. Liveness will be computed for both image_1 and image_2 when set as true. 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.
## Response `200`
Successful Response
- ResponseCompareFace
- `status_code` string: Status Code
- `message` string, required: Message
- `session_id` string: unique id to represent transaction record
- `image_1` object: Image 1
- `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
- `nface` integer: Shows how many faces are detected in the input image.
- `bounding_box` object: Shows result of 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
- `image_2` object: Image 1
- `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
- `nface` integer: Shows how many faces are detected in the input image.
- `bounding_box` object: Shows result of 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
- `similarity_status` boolean: Shows similarity result
- `timestamp` number: Shows time which face compared 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)