FACE_IDU_WEB_CheckResult - ID Verification - Alibaba Cloud Documentation Center

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

Description

API operation: CheckResult
Request method: HTTPS POST
Description: After you receive a callback notification, you can call this API operation on the server to retrieve the authentication status and data.
Important
ID Verification service results are stored for 30 days by default and are automatically deleted after this period. You must retrieve the authentication results within 30 days after the authentication is complete.
For API-specific QPS limits, see ID Verification server-side API QPS limits.
Endpoints:
Note
An internal same-region endpoint is used for communication between Alibaba Cloud products within the same region. If your business server is deployed in the same Alibaba Cloud region, you can use an internal same-region endpoint to access the ID Verification service for more secure and stable network communication.
Singapore
- Public endpoint: cloudauth-intl.ap-southeast-1.aliyuncs.com
- Internal same-region endpoint: cloudauth-intl-vpc.ap-southeast-1.aliyuncs.com
Indonesia
- Public endpoint: cloudauth-intl.ap-southeast-5.aliyuncs.com
- Internal same-region endpoint: cloudauth-intl-vpc.ap-southeast-5.aliyuncs.com
China (Hong Kong)
- Public endpoint: cloudauth-intl.cn-hongkong.aliyuncs.com
- Internal same-region endpoint: cloudauth-intl-vpc.cn-hongkong.aliyuncs.com

Online debugging and integration

Note

Before you start debugging and integration, review the Use OpenAPI to debug and integrate server-side APIs document to learn how to call API operations on the OpenAPI platform and obtain the SDK and sample code.

Use OpenAPI Explorer to run and debug this API operation, and to generate SDK code examples.

Request parameters

Name	Type	Required	Description	Example
MerchantBizId	String	Yes	A unique business ID that you customize to track and troubleshoot issues. It can be a combination of letters and digits, up to 32 characters in length. Make sure the ID is unique. Note Alibaba Cloud does not check the uniqueness of this value. For better tracking, make sure this ID is unique.	e0c34a77f5ac40a5aa5e6ed20c35****
TransactionId	String	Yes	The unique identifier for the entire authentication flow. You must call the Initialize API operation to obtain this value. Important To prevent tampering, you must use the TransactionId stored on your server from the Initialize API operation call. Do not use the TransactionId from the client-side callback.	hksb7ba1b28130d24e015d6********
IsReturnImage	String	No	Specifies whether to return authentication image data: 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-5384FF0****
	Code	String	The response code.	Success
	Message	String	A detailed description of the response code.	success
	Result.Passed	String	The final authentication result. Valid values: Y: Passed N: Failed	Y
	Result.SubCode	String	A description of the authentication result. For more information, see ResultObject.SubCode error codes.	200
	Result.ExtFaceInfo	String	Information about the facial recognition result. For the JSON format, see the example on the right. For more information, see ExtFaceInfo.	`{ "faceAttack": "N", "faceImg": "/9j/4AAQSkZJRgABAQAAAQqviV6oakp8...", "docVideoUrl": "https://aliyun-cloudauth.oss-aliyuncs.com/******.webm" }`
	Result.ExtInfo	String	Additional information from the authentication process. For more information, see ExtInfo.	`{ "procedurePriority": "keep" }`

ExtFaceInfo

Name	Type	Description	Example
faceImg	String	The captured face image in Base64 format. This field is returned if you set the isReturnImage parameter to `Y` in the request and the face scan process is completed.	Base64 format
faceAttack	String	Indicates whether a liveness attack was detected on the captured face: Y: Attack detected N: Not applicable	N
docVideoUrl	String	The OSS download URL for the evidence file. Note The URL for the evidence video is valid for 15 minutes. You can query and obtain the URL multiple times within 30 minutes after the authentication is complete. After 30 minutes, the system automatically deletes the evidence video file, and it cannot be recovered. Download and save the file promptly.	https://aliyun-cloudauth.oss-aliyuncs.com/******.webm
faceAge	String	The predicted reference age of the face. This field may not be returned if the prediction fails.	30
faceGender	String	The predicted gender from the face image. This field may not be returned if the prediction fails. M: Male F: Female	M
faceAttackScore	Double	The probability of a spoofing attack as predicted by the facial recognition algorithm. A higher score indicates a higher probability of a spoofing attack. Value range: 0 to 100.	80
guardRiskScore	Double	The probability of device risk as predicted by the Face Guard algorithm. A higher score indicates a higher device risk. Value range: 0 to 100.	90
faceComparisonScore	Double	The face comparison score. This parameter is returned only when the verification mode is included. Value range: 0 to 100. The default system threshold is 90. You can also customize the decision based on your business needs.	90
faceRegistrationResult	String	Indicates whether the face registration was successful: 1: Success 0: Failure	1
faceRegistrationID	String	The face registration ID. This parameter is returned only when auto-registration is enabled and the face registration is successful.	f5a9219aefd6*******c84c8f0ca592a
duplicateFace	String	Duplicate face information. If a duplicate face is found during retrieval, the corresponding face ID from the face database is returned.	`[ { "faceGroupCode": "sg7**uzt", "faceId": "f5a921*****9e792ec84c8f0ca592a" } ]`

ExtInfo

Name

Type

Description

Example

procedurePriority

String

Authentication fallback methods:

keep: No alternative method.
url: URL alternative method.

keep

Return code

HTTP status code	Code	Message description
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.

ResultObject.SubCode error codes

Error code	Is the authentication record billed?	Description and suggestion
200	Yes	Authentication passed.
204	Yes	The face comparison failed. The person may be different or the liveness photo is of low quality.
205	Yes	The liveness detection found a threat.
206	Yes	Business policy restriction. Note If safe mode is enabled, the service performs security checks on the device and environment used for authentication. If a potential threat is detected, the authentication fails. Remind the user to uninstall software or plug-ins such as multi-instance applications, app cloners, or virtual environments from their device. After the device is restored to its initial secure environment, ask the user to retry.
233	Yes	A similar face was detected.