Image Passive Liveliness

Introduction

The Image Passive Liveness API helps in detecting if a live person is present in front of the camera during the onboarding process. This API is useful for identifying any spoofing attacks by fraudsters. It is recommended to use this API in conjunction with the Signzy face match solution. This documentation provides details on how to call the API, input guidelines, sample responses, and other relevant information.

API details

Endpoint

POST https://api.signzy.app/api/v3/image/passive_liveliness

POST https://api-preproduction.signzy.app/api/v3/image/passive_liveliness

Request Headers

Name	Value	Required	Description
Content-Type	application/json	Mandatory	The type of content that the request body contains.
Authorization	XXXXXXXXXXXXXXX	Mandatory	An authentication token to authorize the request. Reach out to the Signzy support team to get one created.

Request body parameters

Parameter	Data Type	Description	Required
image	String	Input image URL	Mandatory
strict	Boolean	To enable strict mode for the model. The default value is false (strict mode enforces more robust checks for liveliness, rejecting cases where the face is not very clear based on the given image requirements below)	Optional
showQuality	Boolean	Optional boolean parameter (default: false). When set to true, the API response will include additional quality and probability scores along with the default output values.

{
    "image": "image-url"
}

Code samples

curl --location 'https://api.signzy.app/api/v3/image/passive_liveliness' \
--header 'Content-Type: application/json' \
--header 'Authorization: <Access-Token>' \
--data '{
    "image": "input-image-url"
}'

Response body parameters

Parameter	Data Type	Description
result	Object	Contains the liveliness result of the input image.
result.liveness	Boolean	"true" if the image is live else "false"
result.score	Float	LIveliness score of the input image. The value can be between 0 and 1.
result.quality	Float	Included in the response only when the showquality parameter is enabled in the request. Indicates the quality score of the provided image.
result.probability	Float	Included in the response only when the showquality parameter is enabled in the request. Represents the model’s probability score for the returned result.

{
    "result": {
        "liveness": false,
        "score": 0
    }
}

// showQuality parameter set to true
{
    "result": {
        "liveness": false,
        "score": 0,
        "quality": 1,
        "probability":0
    }
}


// Face not detected
{
    "result": {
        "message": "face not detected",
        "name": "error",
        "status": 400,
        "reason": "FACE_NOT_FOUND",
        "type": "Bad Request",
        "statusCode": 400
    }
}

// Multiple face detected
{
    "result": {
        "message": "multiple faces detected",
        "name": "error",
        "status": 400,
        "reason": "MULITPLE_FACES_FOUND",
        "type": "Bad Request",
        "statusCode": 400
    }
}

If strict=true is passed in the request then the strict liveliness check model will be used and to get the best results please follow the below-mentioned guidelines.

The size of the document should not exceed 5 MB.
The image should be clicked in a well-lit room, with the face shown clearly to the camera. Extreme darkness/brightness on the face might result in the API behaving unexpectedly.
The complete face should be clearly visible in the image. Tilted faces might result in API behaving unexpectedly.
The minimum size of the detected face should be 224X224 pixels.
Motion Blur might result in API behaving unexpectedly.
Any occlusions on parts of the face like Glasses and masks should be removed while performing a Liveness Check.
The detected Face should occupy at least 20% of the total image area.
The image should be clicked as a selfie (portrait mode only).
No image compression is highly recommended for accurate results.

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.

We value your feedback and are committed to making your experience smooth and enjoyable. Our team is dedicated to assisting you with any needs you may have. Thank you for choosing our services. We look forward to helping you!