---
title: "Sandbox - Search Face"
method: POST
path: "/v1/face/search"
tags: ["Face"]
---
# Sandbox - Search Face
`POST /v1/face/search`
This method helps you search similar faces with specific image
The following table describes the image option to be used as input.
Image scenario consists of Person A to J. Person is described in the last character: _A means person A, _B means person B, up until _J means person_J. Besides, image scenario consists of number of face in single image 1-9. Number of Face is described in the last character, which are _1 means 1 face in photo, _2 means 2 face in photo.
| Images | Description |
|---------------------------------|-----------------------------------------------------------------------------------------------------------|
| IMAGE_EXCEED_LIMIT | Photo with size > 5MiB |
| NO_FACE_PHOTO | Photo with no face detected |
| LIVE_PERSON_A_N | Photo of Live Person (A) |
| LIVE_PERSON_M_A_N | Photo of Live Person (A) wearing Mask |
| LIVE_PERSON_V_A_N | Photo of Live Person (A) wearing Veil |
| LIVE_PERSON_S_A_N | Photo of Live Person (A) wearing Sunglasses |
| LIVE_PERSON_MV_A_N | Photo of Live Person (A) wearing Mask, Veil |
| LIVE_PERSON_MS_A_N | Photo of Live Person (A) wearing Mask, Sunglasses |
| LIVE_PERSON_VS_A_N | Photo of Live Person (A) wearing Veil, Sunglasses |
| LIVE_PERSON_MVS_A_N | Photo of Live Person (A) wearing Mask, Veil, Sunglasses |
| LIVE_PERSON_BLUR_A_N | Photo of Live Person (A) with blur condition |
| LIVE_PERSON_DARK_A_N | Photo of Live Person (A) with dark condition |
| LIVE_PERSON_BLURDARK_A_N | Photo of Live Person (A) with blur and dark condition |
| LIVE_PERSON_BLUR_M_A_N | Photo of Live Person (A) wearing Mask, with blur condition |
| LIVE_PERSON_BLUR_V_A_N | Photo of Live Person (A) wearing Veil, with blur condition |
| LIVE_PERSON_BLUR_S_A_N | Photo of Live Person (A) wearing Sunglasses, with blur condition |
| LIVE_PERSON_BLUR_MV_A_N | Photo of Live Person (A) wearing Mask, Veil, with blur condition |
| LIVE_PERSON_BLUR_MS_A_N | Photo of Live Person (A) wearing Mask, Sunglasses with blur condition |
| LIVE_PERSON_BLUR_VS_A_N | Photo of Live Person (A) wearing Veil, Sunglasses, with blur condition |
| LIVE_PERSON_BLUR_MVS_A_N | Photo of Live Person (A) wearing Mask, Veil, Sunglasses, with blur condition |
| LIVE_PERSON_DARK_M_A_N | Photo of Live Person (A) wearing Mask, with dark condition |
| LIVE_PERSON_DARK_V_A_N | Photo of Live Person (A) wearing Veil, with dark condition |
| LIVE_PERSON_DARK_S_A_N | Photo of Live Person (A) wearing Sunglasses, with dark condition |
| LIVE_PERSON_DARK_MV_A_N | Photo of Live Person (A) wearing Mask, Veil, with dark condition |
| LIVE_PERSON_DARK_MS_A_N | Photo of Live Person (A) wearing Mask, Sunglasses, with dark condition |
| LIVE_PERSON_DARK_VS_A_N | Photo of Live Person (A) wearing Veil, Sunglasses with blur and dark condition |
| LIVE_PERSON_DARK_MVS_A_N | Photo of Live Person (A) wearing Mask, Veil, Sunglasses, with dark condition |
| LIVE_PERSON_BLURDARK_M_A_N | Photo of Live Person (A) wearing Mask, with blur and dark condition |
| LIVE_PERSON_BLURDARK_V_A_N | Photo of Live Person (A) wearing Veil, with blur and dark condition |
| LIVE_PERSON_BLURDARK_S_A_N | Photo of Live Person (A) wearing Sunglasses, with blur and dark condition |
| LIVE_PERSON_BLURDARK_MV_A_N | Photo of Live Person (A) wearing Mask, Veil, with blur and dark condition |
| LIVE_PERSON_BLURDARK_MS_A_N | Photo of Live Person (A) wearing Mask, Sunglasses, with blur and dark condition |
| LIVE_PERSON_BLURDARK_VS_A_N | Photo of Live Person (A) wearing Veil, Sunglasses with blur and blur and dark condition |
| LIVE_PERSON_BLURDARK_MVS_A_N | Photo of Live Person (A) wearing Mask, Veil, Sunglasses, with blur and dark condition |
| SPOOF_PERSON_A_N | Photo of Spoof Person (A) |
| SPOOF_PERSON_M_A_N | Photo of Spoof Person (A) wearing Mask |
| SPOOF_PERSON_V_A_N | Photo of Spoof Person (A) wearing Veil |
| SPOOF_PERSON_S_A_N | Photo of Spoof Person (A) wearing Sunglasses |
| SPOOF_PERSON_MV_A_N | Photo of Spoof Person (A) wearing Mask, Veil |
| SPOOF_PERSON_MS_A_N | Photo of Spoof Person (A) wearing Mask, Sunglasses |
| SPOOF_PERSON_VS_A_N | Photo of Spoof Person (A) wearing Veil, Sunglasses |
| SPOOF_PERSON_MVS_A_N | Photo of Spoof Person (A) wearing Mask, Veil, Sunglasses |
| SPOOF_PERSON_BLUR_A_N | Photo of Spoof Person (A) with blur condition |
| SPOOF_PERSON_DARK_A_N | Photo of Spoof Person (A) with dark condition |
| SPOOF_PERSON_BLURDARK_A_N | Photo of Spoof Person (A) with blur and dark condition |
| SPOOF_PERSON_GRAY_A_N | Photo of Spoof Person (A) in grayscale image |
| SPOOF_PERSON_GRAY_M_A_N | Photo of Spoof Person (A) in grayscale image wearing Mask |
| SPOOF_PERSON_GRAY_V_A_N | Photo of Spoof Person (A) in grayscale image wearing Veil |
| SPOOF_PERSON_GRAY_S_A_N | Photo of Spoof Person (A) in grayscale image wearing Sunglasses |
| SPOOF_PERSON_GRAY_MV_A_N | Photo of Spoof Person (A) in grayscale image wearing Mask, Veil |
| SPOOF_PERSON_GRAY_MS_A_N | Photo of Spoof Person (A) in grayscale image wearing Mask, Sunglasses |
| SPOOF_PERSON_GRAY_VS_A_N | Photo of Spoof Person (A) in grayscale image wearing Veil, Sunglasses |
| SPOOF_PERSON_GRAY_MVS_A_N | Photo of Spoof Person (A) in grayscale image wearing Mask, Veil, Sunglasses |
| SPOOF_PERSON_GRAYBLUR_A_N | Photo of Spoof Person (A) in grayscale image with blur condition |
| SPOOF_PERSON_GRAYDARK_A_N | Photo of Spoof Person (A) in grayscale image with dark condition |
| SPOOF_PERSON_GRAYBLURDARK_A_N | Photo of Spoof Person (A) in grayscale image with blur and dark condition |
| SPOOF_PERSON_BLUR_M_A_N | Photo of Spoof Person (A) wearing Mask, with blur condition |
| SPOOF_PERSON_BLUR_V_A_N | Photo of Spoof Person (A) wearing Veil, with blur condition |
| SPOOF_PERSON_BLUR_S_A_N | Photo of Spoof Person (A) wearing Sunglasses, with blur condition |
| SPOOF_PERSON_BLUR_MV_A_N | Photo of Spoof Person (A) wearing Mask, Veil, with blur condition |
| SPOOF_PERSON_BLUR_MS_A_N | Photo of Spoof Person (A) wearing Mask, Sunglasses with blur condition |
| SPOOF_PERSON_BLUR_VS_A_N | Photo of Spoof Person (A) wearing Veil, Sunglasses, with blur condition |
| SPOOF_PERSON_BLUR_MVS_A_N | Photo of Spoof Person (A) wearing Mask, Veil, Sunglasses, with blur condition |
| SPOOF_PERSON_DARK_M_A_N | Photo of Spoof Person (A) wearing Mask, with dark condition |
| SPOOF_PERSON_DARK_V_A_N | Photo of Spoof Person (A) wearing Veil, with dark condition |
| SPOOF_PERSON_DARK_S_A_N | Photo of Spoof Person (A) wearing Sunglasses, with dark condition |
| SPOOF_PERSON_DARK_MV_A_N | Photo of Spoof Person (A) wearing Mask, Veil, with dark condition |
| SPOOF_PERSON_DARK_MS_A_N | Photo of Spoof Person (A) wearing Mask, Sunglasses, with dark condition |
| SPOOF_PERSON_DARK_VS_A_N | Photo of Spoof Person (A) wearing Veil, Sunglasses with blur and dark condition |
| SPOOF_PERSON_DARK_MVS_A_N | Photo of Spoof Person (A) wearing Mask, Veil, Sunglasses, with dark condition |
| SPOOF_PERSON_BLURDARK_M_A_N | Photo of Spoof Person (A) wearing Mask, with blur and dark condition |
| SPOOF_PERSON_BLURDARK_V_A_N | Photo of Spoof Person (A) wearing Veil, with blur and dark condition |
| SPOOF_PERSON_BLURDARK_S_A_N | Photo of Spoof Person (A) wearing Sunglasses, with blur and dark condition |
| SPOOF_PERSON_BLURDARK_MV_A_N | Photo of Spoof Person (A) wearing Mask, Veil, with blur and dark condition |
| SPOOF_PERSON_BLURDARK_MS_A_N | Photo of Spoof Person (A) wearing Mask, Sunglasses, with blur and dark condition |
| SPOOF_PERSON_BLURDARK_VS_A_N | Photo of Spoof Person (A) wearing Veil, Sunglasses with blur and blur and dark condition |
| SPOOF_PERSON_BLURDARK_MVS_A_N | Photo of Spoof Person (A) wearing Mask, Veil, Sunglasses, with blur and dark condition |
| SPOOF_PERSON_GRAYBLUR_M_A_N | Photo of Spoof Person (A) in grayscale image, wearing Mask, with blur condition |
| SPOOF_PERSON_GRAYBLUR_V_A_N | Photo of Spoof Person (A) in grayscale image, wearing Veil, with blur condition |
| SPOOF_PERSON_GRAYBLUR_S_A_N | Photo of Spoof Person (A) in grayscale image, wearing Sunglasses, with blur condition |
| SPOOF_PERSON_GRAYBLUR_MV_A_N | Photo of Spoof Person (A) in grayscale image, wearing Mask, Veil, with blur condition |
| SPOOF_PERSON_GRAYBLUR_MS_A_N | Photo of Spoof Person (A) in grayscale image, wearing Mask, Sunglasses, with blur condition |
| SPOOF_PERSON_GRAYBLUR_VS_A_N | Photo of Spoof Person (A) in grayscale image, wearing Veil, Sunglasses, with blur condition |
| SPOOF_PERSON_GRAYBLUR_MVS_A_N | Photo of Spoof Person (A) in grayscale image, wearing Mask, Veil, Sunglasses with blur condition |
| SPOOF_PERSON_GRAYDARK_M_A_N | Photo of Spoof Person (A) in grayscale image, wearing Mask, with dark condition |
| SPOOF_PERSON_GRAYDARK_V_A_N | Photo of Spoof Person (A) in grayscale image, wearing Veil, with dark condition |
| SPOOF_PERSON_GRAYDARK_S_A_N | Photo of Spoof Person (A) in grayscale image, wearing Sunglasses, with dark condition |
| SPOOF_PERSON_GRAYDARK_MV_A_N | Photo of Spoof Person (A) in grayscale image, wearing Mask, Veil, with dark condition |
| SPOOF_PERSON_GRAYDARK_MS_A_N | Photo of Spoof Person (A) in grayscale image, wearing Mask, Sunglasses, with dark condition |
| SPOOF_PERSON_GRAYDARK_VS_A_N | Photo of Spoof Person (A) in grayscale image, wearing Veil, Sunglasses, with dark condition |
| SPOOF_PERSON_GRAYDARK_MVS_A_N | Photo of Spoof Person (A) in grayscale image, wearing Mask, Veil, Sunglasses with dark condition |
| SPOOF_PERSON_GRAYBLURDARK_M_A_N | Photo of Spoof Person (A) in grayscale image, wearing Mask, with blur and dark condition |
| SPOOF_PERSON_GRAYBLURDARK_V_A_N | Photo of Spoof Person (A) in grayscale image, wearing Veil, with blur and dark condition |
| SPOOF_PERSON_GRAYBLURDARK_S_A_N | Photo of Spoof Person (A) in grayscale image, wearing Sunglasses, with blur and dark condition |
| SPOOF_PERSON_GRAYBLURDARK_MV_A_N | Photo of Spoof Person (A) in grayscale image, wearing Mask, Veil, with blur and dark condition |
| SPOOF_PERSON_GRAYBLURDARK_MS_A_N | Photo of Spoof Person (A) in grayscale image, wearing Mask, Sunglasses, with blur and dark condition |
| SPOOF_PERSON_GRAYBLURDARK_VS_A_N | Photo of Spoof Person (A) in grayscale image, wearing Veil, Sunglasses, with blur and dark condition |
| SPOOF_PERSON_GRAYBLURDARK_MVS_A_N | Photo of Spoof Person (A) in grayscale image, wearing Mask, Veil, Sunglasses with blur and dark condition |
The following table describes image similarity. Only the same photo could give 100% similarity.
| SIMILARITY | A | B | C | D | E | F | G | H | I | J |
|------------|-------|------|------|------|------|------|------|------|------|-----|
| A | 100 | | | | | | | | | |
| B | 90.93 | 100 | | | | | | | | |
| C | 88.4 | 83.5 | 100 | | | | | | | |
| D | 95.5 | 98.5 | 70.4 | 100 | | | | | | |
| E | 60.5 | 55.7 | 30.3 | 88.6 | 100 | | | | | |
| F | 0 | 15.6 | 80.5 | 78.4 | 68.4 | 100 | | | | |
| G | 15.9 | 33.3 | 44.5 | 0 | 75.9 | 95.4 | 100 | | | |
| H | 0 | 55.8 | 0 | 78.9 | 85.7 | 90.2 | 81.4 | 100 | | |
| I | 42.8 | 0 | 45.7 | 83.4 | 0 | 89.6 | 82.5 | 0 | 100 | |
| J | 0 | 13.8 | 67.6 | 0 | 66.9 | 54.7 | 23.4 | 87.9 | 92.4 | 100 |
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 code | Description |
| ------------------------------|:---------------------------------------------|
| INVALID_PAYLOAD | no value in payload or empty string more than 1 |
| INVALID_PAYLOAD_IMAGE_SIZE | invalid payload image size too large |
| INVALID_PAYLOAD_IMAGE_MISSING | image empty string |
| MISSING_PAYLOAD_IMAGE | missing payload image |
| INVALID_PAYLOAD_THRESHOLD | threshold cannot lower than 0 or more than 100 |
| INVALID_PAYLOAD_LIMIT | limit cannot lower than 1 or more than 10 |
| FACE_NOT_DETECTED | face not detected from image |
| INVALID_SANDBOX_IMAGE_CODE | image not exist in image code sandbox |
| INVALID_SANDBOX_IDENTITY | identity of image not between A-J |
| INVALID_SANDBOX_NFACE | number of face in image not 1-9|
| INVALID_PAYLOAD_QUALITY_VALIDATION_DEPENDENCY | is_quality must be true if validate_quality true |
| INVALID_PAYLOAD_ATTRIBUTE_VALIDATION_DEPENDENCY | is_attribute must be true if validate_attribute true |
| INVALID_PAYLOAD_LIVENESS_VALIDATION_DEPENDENCY | is_liveness must be true if validate_liveness true |
| FAIL_ON_1 | fail on liveness |
| FAIL_ON_2 | fail on attribute |
| FAIL_ON_3 | fail on liveness and attribute |
| FAIL_ON_4 | fail on quality |
| FAIL_ON_5 | fail on liveness and quality |
| FAIL_ON_6 | fail on attribute and quality |
| FAIL_ON_7 | fail on liveness, attribute, and quality |
|FAIL_ON_8 |fail on number of face (nface)|
|FAIL_ON_9 |fail on number of face (nface) and liveness|
|FAIL_ON_10 |fail on nfail on number of face (nface) and attribute|
|FAIL_ON_11 |fail on number of face (nface), attribute, and liveness|
|FAIL_ON_12 |fail on number of face (nface) and quality|
|FAIL_ON_13 |fail on number of face (nface), quality, and liveness|
|FAIL_ON_14 |fail on number of face (nface), quality, and attribute|
|FAIL_ON_15 |fail on number of face (nface), quality, attribute, and liveness|
| INTERNAL_SERVER_ERROR | internal server error |
## Headers
- `App-ID` string, required
- `API-Key` string, required
## Request body
- SearchFace
- `image` string, required — choice of image, as given in the table
- `limit` number — A number indicating search limit (1 to 10), defaults to 1
- `return_image` boolean — A flag to return base64 image in matches, defaults to false
- `threshold` number — A number indicating threshold for confidence (0 to 100), defaults to 82
- `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
- `validate_quality` boolean — Determines whether Quality validation will be executed. The validation consists of checking blur and dark with threshold 50, 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.
- `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. (New)
## Response `200`
Successful Response
- ResponseSearchFace
- `status_code` string — Status Code
- `message` string, required — Message
- `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
- `rotation` integer — Shows how many rotations need to be done to detect face in image
- `timestamp` number — Shows time which face enrolled successfully
- `nface` integer — Shows how many faces are detected in the input image. (New)
- `matches` object[] — Shows similar face matches as limit (defaults to 1)
- `subject_id` string — Shows respected subject_id of similar matches
- `image` string — Shows respected image of similar matches in base64 format
## Other responses
- `400` — Bad Request
- `401` — Unauthorized
- `500` — Internal Server Error
---
[API](https://skmtc.net/verihubs/apis/sms-api-documentation.md) · [All operations](https://skmtc.net/verihubs/apis/sms-api-documentation/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/verihubs/sms-api-documentation/versions/5fa885d38adc/schema)