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/checks

POST  https://api-preproduction.signzy.app/api/v3/face/checks

Request body parameters

Parameter	Type	Required	Description
image	string	Yes	Persist file URL (Supported file types are jpg, jpeg, png, pdf, tiff)

JSON

{ "image": "image url" }

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.