---
title: "Enroll Face"
method: POST
path: "/v1/face/enroll"
tags: ["Face"]
---
# Enroll Face
`POST /v1/face/enroll`
## Request
- Base URL: `https://api.verihubs.com`
- URL: `https://api.verihubs.com/v1/face/enroll`
- Auth: none declared. Required headers: `App-ID`, `API-Key`
This method helps you to enroll image containing face.
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 |
| 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_SUBJECT_ID_MISSING | invalid payload subject id is empty string |
|400 | INVALID_PAYLOAD_IMAGE_SIZE | invalid payload image size too large |
|400 | MISSING_PAYLOAD_IMAGE | missing payload image |
|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_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 |
|403 | INSUFFICIENT_QUOTA_ENROLL | usage reach it quota limit for enroll (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
- EnrollFace
- `image` string, required: A base64 or URL image file.
- `subject_id` string: used to update enrolled photo.
- `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, and also checking whether the image is a black & white image (grayscale is 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_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.
## Response `200`
Successful Response
- ResponseEnrollFace
- `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 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
- `nface` integer: Shows how many faces are detected in the input image.
- `timestamp` number: Shows time which face enrolled successfully
## Other responses
- `201`: Successful Response (Insert New)
- `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)