Face Compare API

This method helps you to compare faces between two images.

Endpoint

Method	Endpoint
POST	`https://api.verihubs.com/v1/face/compare`

Request

Headers

Key	Type	Notes	Description
App-ID	String	Required	Application ID that generated from Application Menu in Verihubs Client Dashboard. To hit in Testing and Live mode you need a Production Application ID.
API-Key	String	Required	API-Key that generated from Application Menu in Verihubs Client Dashboard that related to specific Application ID.

You can generate your Application ID and API-Key in the Application page in Verihubs Client Dashboard..

Body Parameters

Parameter	Type	Notes	Default	Description
image_1	String	Required		A base64 or URL image file. Image Type JPEG, JPG, PNG. Max File size: 5MB. Recommended image ratio 4:3. If the photo is not a face image, it will return "face not detected".
image_2	String	Required		A base64 or URL image file. Image Type JPEG, JPG, PNG. Max File size: 5MB. Recommended image ratio 4:3. If the photo is not a face image, it will return "face not detected".
is_quality	boolean	optional	true	Determines whether Image Quality (blur and dark) will be computed and return as result
is_attribute	boolean	optional	true	Determines whether Image Attribute (sunglasses, mask, veil, hat, and face blocker object) will be detected and return as result
is_liveness	boolean	optional	true	Determines whether Passive Liveness will be computed and return as result
validate_quality	boolean	optional	false	Determines whether Quality validation will be executed. The validation consists of checking blur and dark. "validate_quality" can be TRUE only when "is_quality" is TRUE.
validate_attribute	boolean	optional	false	Determines whether Attribute validation will be executed. The validation consists of checking whether sunglasses, mask, or face blocker is detected in the input image. "validate_attribute" can be TRUE only when is_attribute is TRUE.
validate_liveness	boolean	optional	false	Determines whether Liveness validation will be executed. The validation checks whether input image is live / spoof. "validate_liveness" can be TRUE only when "is_liveness" is TRUE.
validate_nface	boolean	optional	false	Determines whether the number of faces validation will be executed. The validation checks whether the input image consists of more than one face.
threshold	string	optional	"moderate"	threshold can be selected based on security level: "BASIC", "MODERATE", "HIGH"
image_1_id	boolean	optional	false	Determines whether the input image in payload "image_1" is ID / KTP image. By setting the value to TRUE, the system will consider all "image_1" is ID / KTP and focus on extracting only the face image from the ID / KTP.
image_2_id	boolean	optional	false	Determines whether the input image in payload "image_2" is ID / KTP image. By setting the value to TRUE, the system will consider all "image_1" is ID / KTP and focus on extracting only the face image from the ID / KTP.

Responses

Response Code

Code	Description
200	Successful Response
400	Bad Request
401	Unauthorized
500	Internal Server Error

Details for 200 and 201

Key	Type	Description
message	string	Message that describe the overall response.
status_code	string	Status that indicate the billing calculation. See status code list in this link.
image_1	object	Describes detail for image 1
image_2	object	Describes detail for image 2
image_quality	object	Describes image quality detail, consist of blur and dark
blur	boolean	Describes whether input image is considered as blur (If it exceeds the threshold, it will detected as blur)
dark	boolean	Describes whether input image is considered as dark (If it exceeds the threshold, it will detected as dark)
attributes	object	Describes image attributes detail
sunglasses_on	boolean	Describes whether sunglasses is detected on input image
mask_on	boolean	Describes whether mask is detected on input image
veil_on	boolean	Describes whether veil is detected on input image
hat_on	boolean	Describes whether hat is detected on input image
face_blocker	boolean	Describes whether any object is detected blocking the face on input image
liveness	object	Describes liveness detail
status	boolean	Describes whether the input image is considered as real or spoof
probability	string	Describes the liveness score (0 or 100)
rotation	integer	Shows rotation degrees 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 when the process is successfully done
similarity_status	boolean	Shows similarity status of inputted image and enrolled image. The similarity_status is “true” if the similarity score >= threshold, and similarity_status is “false” if similarity score < threshold.

Error Code

Response Code	Error Message	Description
400	INVALID_PAYLOAD	no value in payload or empty string more than 1
400	INVALID_PAYLOAD_IMAGE_1_MISSING	invalid payload image 1 not a standard b64/url or image empty string
400	INVALID_PAYLOAD_IMAGE_2_MISSING	invalid payload image 2 not a standard b64/url or image empty string
400	INVALID_PAYLOAD_IMAGE_1_SIZE	invalid payload image 1 size too large
400	INVALID_PAYLOAD_IMAGE_2_SIZE	invalid payload image 2 size too large
400	MISSING_PAYLOAD_IMAGE_1	missing payload image 1
400	MISSING_PAYLOAD_IMAGE_2	missing payload image 2
400	INVALID_PAYLOAD_IMAGE_1_TIMEOUT	timeout getting image 1 from url in 15 seconds
400	INVALID_PAYLOAD_IMAGE_2_TIMEOUT	timeout getting image 2 from url in 15 seconds
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
400	INVALID_PAYLOAD_THRESHOLD_MISSING	threshold choice is incorrect
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
200	FAIL_ON_16	fail on similarity status
403	INSUFFICIENT_QUOTA_COMPARE	usage reach it quota limit for compare (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

Sample Responses

Response Code	Response	Descriptions
200	{ "message": "Request Success", "session_id": "6822277b-c13b-4945-94e1-07a07547f696", "timestamp": 1677057455.230828, "status_code": "FACE-3", "similarity_status": true, "image_1": { "nface_1": 1, "rotation": 0, "bounding_box": { "TopLeftX": "246.7519989013672", "TopLeftY": "151.1721649169922", "BottomRightX": "747.3502807617188", "BottomRightY": "794.275146484375", "Width": "500.59828186035156", "Height": "643.1029815673828" }, "face_landmark": { "LeftEyeX": "369.9593200683594", "LeftEyeY": "398.721923828125", "RightEyeX": "600.0042114257812", "RightEyeY": "395.2314147949219", "NoseX": "481.2694396972656", "NoseY": "502.7786865234375", "MouthLeftX": "392.0671691894531", "MouthLeftY": "619.5045776367188", "MouthRightX": "594.3441162109375", "MouthRightY": "616.2847290039062" }, "attributes": { "sunglasses_on": false, "veil_on": true, "mask_on": false, "hat_on": false, "face_blocker": false }, "image_quality": { "blur": false, "dark": false }, "liveness": { "status": false, "probability": "0" }, "liveness_status": false }, "image_2": { "rotation": 0, "nface_2": 1, "bounding_box": { "TopLeftX": "246.7519989013672", "TopLeftY": "151.1721649169922", "BottomRightX": "747.3502807617188", "BottomRightY": "794.275146484375", "Width": "500.59828186035156", "Height": "643.1029815673828" }, "face_landmark": { "LeftEyeX": "369.9593200683594" }	Request data parameter is valid.
400	`"message": "Invalid Payload", "data": { "message": "Syntax error" }`	Invalid Payload. Transaction that is considered failed due to validation errors, an error_field will appear explaining the error.
400	`{ "message": "Face not detected in image", "error_code": "FACE_NOT_DETECTED" }`	Request image is invalid (not a face image).
401	`{ "message": "Authorization failed" }`	Authorization Failed; Transaction that unauthorized due to Application ID or API-Key issue. To hit in Testing and Live mode you need a Production Application ID and API-Key.
403	`{ "message": "Insufficient compare quota", "error_code": "INSUFFICIENT_QUOTA_COMPARE" }`	The transaction is in Testing mode and not enough remaining quota. Please contact Verihubs Customer Support.
500	`{ "message": "Internal server error" }`	Internal server error.