Face Checks API
Introduction
The Face Checks API analyzes a single selfie image and returns a structured set of face-quality checks used during KYC onboarding. Given one image, the API detects the face and returns deterministic boolean attributes — accessory presence, per-feature visibility, eye state — along with a face clarity score.
This allows onboarding flows to programmatically accept an image, reject it, or prompt the user to retake before passing it on for identity matching. The endpoint is synchronous and stateless: one image in, one structured result out.
API Details
Endpoint:
POST https://api.signzy.app/api/v3/face/checksPOST https://api-preproduction.signzy.app/api/v3/face/checksRequest body parameters
Parameter | Type | Required | Description |
|---|---|---|---|
image | string | Yes | Persist file URL (Supported file types are jpg, jpeg, png, pdf, tiff) |
JSON
Request headers
Name | Value | Required | Description |
|---|---|---|---|
Content-Type | application/json | Yes | The type of content that the request body contains. |
Authorization | XXXXXXXXXXX | Yes | An authentication token to authorize the request. Reach out to the Signzy support team to get one created. |
Code samples
Code samples:
curl --location 'https://api-preproduction.signzy.app/api/v3/face/checks' \
--header 'Content-Type: application/json' \
--header 'Authorization: <auth_key>' \
--data '{
"image": "img_url"
}'Response body parameters
Group | Parameter | Data type | Description |
|---|---|---|---|
execution | execution_id | string | Unique identifier for this execution. Example: 2125bead-c71e-4b39-b547-5f662f6b689d. |
execution | status | string | Processing status of the request. Example: success. |
clarity | output.face_clarity_score | number | Face clarity score as a value between 0 and 1. |
accessories | output.accessories.glasses | bool | Whether the person is wearing glasses. |
accessories | output.accessories.headGears | bool | Whether the person is wearing headgear / a cap. |
accessories | output.accessories.mask | bool | Whether the person is wearing a mask. |
features | output.features.left_eye.visible | bool | Whether the left eye is visible in the image. |
features | output.features.left_eye.open | bool | Whether the left eye is open or closed. |
features | output.features.right_eye.visible | bool | Whether the right eye is visible in the image. |
features | output.features.right_eye.open | bool | Whether the right eye is open or closed. |
features | output.features.mouth.visible | bool | Whether the mouth is visible in the image. |
features | output.features.nose.visible | bool | Whether the nose is visible in the image. |
Response examples
{
"result": {
"execution_id": "2125bead-c71e-4b39-b547-5f662f6b689d",
"status": "success",
"output": {
"face_clarity_score": 1,
"accessories": {
"glasses": false,
"headGears": false,
"mask": false
},
"features": {
"left_eye": {
"visible": true,
"open": true
},
"right_eye": {
"visible": true,
"open": true
},
"mouth": {
"visible": true
},
"nose": {
"visible": true
}
}
}
}
}Contact Us for Any Assistance
If you have any questions or need assistance, please reach out to our customer support team. You can contact us via email at [email protected]. We strive to provide prompt and reliable assistance, ensuring your queries are addressed effectively.