FACE_VERIFY_CheckResult - ID Verification - Alibaba Cloud Documentation Center

This topic describes how to query authentication results using the CheckResult API operation.

API description

API operation: CheckResult

Endpoint: cloudauth-intl.cn-hongkong.aliyuncs.com

Request method: HTTPS POST

Description: After you receive a callback notification, you can call this API operation to obtain the authentication status and materials.

QPS limit: This API is subject to an exclusive queries per second (QPS) limit. For more information, see ID Verification server-side API QPS limits.

Online debugging and integration

Note

Before you debug and integrate, read the Use OpenAPI Explorer to debug and integrate server-side API operations document. It explains how to call API operations on the OpenAPI platform and how to obtain the SDK and its sample code.

You can use OpenAPI Explorer to debug this API operation and generate SDK code examples.

Request parameters

Name	Type	Required	Description	Example
MerchantBizId	String	Yes	A unique business identifier that you customize to track and troubleshoot issues. The identifier can be a combination of letters and digits up to 32 characters in length. Make sure that the identifier is unique. Note Alibaba Cloud servers do not check the uniqueness of this field. For better tracking, ensure that this field is unique.	e0c34a77f5ac40a5aa5e6ed20c35****
TransactionId	String	Yes	The unique identifier for the entire authentication process. Obtain this value by calling the Initialize API operation. Important To prevent tampering threats, this value must be the TransactionId stored on your server from the Initialize API operation call. We do not recommend using the TransactionId from the client-side callback.	hksb7ba1b28130d24e015d6********
IsReturnImage	String	No	Specifies whether to return authentication image materials: Y: Yes N: No (default)	Y

Response parameters

Name		Type	Description	Example
HTTP Status Code		Integer	The HTTP status code.	200
HTTP Body	RequestId	String	The request ID.	130A2C10-B9EE-4D84-88E3-5384FF03****
	Code	String	Response codes.	Success
	Message	String	The detailed description of the response code.	success
	Result.Passed	String	The final authentication result. Valid values: Y: Passed N: Failed	Y
	Result.SubCode	String	The description of the authentication result. For more information, see Error codes for ResultObject.SubCode.	200
	Result.ExtFaceInfo	String	The result information about face liveness verification. For the JSON format, see the example on the right. For more information, see ExtFaceInfo.	`{ "faceAttack": "N", "faceComparisonScore": 99.99, "faceImg": "Base64 format", "facePassed": "Y", "faceQuality": 95.45, "faceOcclusion": "N", "docVideoUrl": "https://aliyun-cloudauth.oss-aliyuncs.com/******.webm" }`

ExtFaceInfo

Name	Type	Description	Example
facePassed	String	Final result of the face liveness verification in the face scan stage: Y: Passed N: Failed	Y
faceComparisonScore	Double	The similarity score between the captured face image and the face image on the document. The score ranges from 0 to 100. Note A higher score indicates a higher probability that the two faces belong to the same person. The default threshold is 90. You can customize the threshold based on your business sample data.	99.99
faceImg	String	The captured face image in the Base64 format. This parameter is returned if you set `isReturnImage=Y` in the request and the face scanning process is completed.	Base64-encoded image
faceAttack	String	Indicates whether a liveness attack was detected during face capture. Valid values: Y: An attack was detected. N: No attack was detected.	N
faceQuality	Double	The quality score of the face image. The score ranges from 0 to 100.	99.99
faceOcclusion	String	Indicates whether the face is occluded. Valid values: Y: The face is occluded. N: The face is not occluded.	N
docVideoUrl	String	The download URL of the evidence in Object Storage Service (OSS). Note The validity period for the URL of the evidence video is 15 minutes. You can repeatedly query and obtain the evidence video within 30 minutes after the verification is complete. After 30 minutes, the system automatically deletes the video file and the video file cannot be restored. Download and save the video within the validity period.	https://aliyun-cloudauth.oss-aliyuncs.com/******.webm
faceAge	String	The predicted age of the individual based on the face image. If the prediction fails, this parameter is not returned.	30
faceGender	String	The predicted gender of the individual based on the face image. If the prediction fails, this parameter is not returned. Valid values: M: Male F: Female	M
faceAttackScore	Double	The probability of a fake face attack predicted by the facial recognition algorithm. A higher score indicates a higher probability of a fake face. The score ranges from 0 to 100.	80
guardRiskScore	Double	The probability of device risk predicted by the face guard algorithm. A higher score indicates a higher device risk. The score ranges from 0 to 100.	90

Response codes

HTTP status code	Code	Message
200	Success	Request successful.
400	MissingParameter	Parameter cannot be empty.
	InvalidParameter	Invalid parameter.
	TransactionIdInvalid	Invalid Transaction ID.
403	Forbidden.RAMUserAccessDenied	You need to grant the RAM user the AliyunAntCloudAuthFullAccess permission. For more information, see Authorize RAM users to access the service.
	Forbidden.AccountAccessDenied	Ensure that you have activated ID verification and your account has no overdue payment.
	Throttling.Api	API request is blocked due to throttling.
404	ProcessNotCompleted	The entire authentication process is not completed.
500	InternalError	Internal system error. Provide feedback to engineers for troubleshooting.

Error codes for ResultObject.SubCode

Error code	Is authentication record billed	Description and suggested reasons
200	Yes	Authentication passed.
204	Yes	Face comparison does not match. This may be a different person or low quality of the liveness photo.
205	Yes	Liveness detection indicates risk.
206	Yes	Business policy restriction. Note When safe mode is enabled, security checks are performed on the authentication device and environment. If risks are detected, the authentication result will fail. You can remind users to uninstall any multiple-instance, clone, virtual environment software or plugins on their device, restore the device to its initial secure state, and try again.