checkresult

2024-11-05 00:31

POST /api/v1/zoloz/connect/checkresult

The ZOLOZ Connect checkresult API is used to request a result about the face verification process results. This API is idempotent.

Structure

Request parameters

Field name

Data type

Max Length

Description

bizId

String

Required. A unique business ID for tracing purpose. For example，the sequence ID from the merchant's business-related database.

Note: The ZOLOZ server does not perform uniqueness check on the value of this field. For better tracking, it is strongly recommended to enable the merchant server to guarantee the uniqueness of the business ID.

transactionId

String

Required. The unique transaction ID that is returned in the response of the initialize API.

Response parameters

Field name	Data type	Description
result	Result	Required. The API request result, which contains information about the result of the API request, such as status and error codes.
connectResult	String	Required. The result of the Connect process. States the actual results of each transaction in the form of Success/Failure/VoidTimeout/InProcess `Success`: Both face quality result and liveness detection have passed. If the Deeper feature is purchased and enabled, it indicates that the overall face quality result, liveness detection result, and Deeper detection result all pass. `Failure`: There is a high risk present in this authentication and rejection is recommended. Face quality result or liveness detection has failed. `VoidTimeout`: Connect results have not been obtained due to timeout. `InProcess`: Connect results have not been obtained, still in progress.
extFaceInfo	ExtFaceInfo	Detailed face verification information. Refer to the table below for details. Optional. Detailed information about face verification. This field is only available when the value of the result.resultCode field is set to `SUCCESS` or `NOT_SAME_PERSON`.

Result

Result process logic

For different request results, different actions are to be performed. See the following for details:

If the value of the result.resultCode is SUCCESS or NOT_SAME_PERSON, the ZOLOZ Connect checkresult API is invoked successfully, and results about face verification are returned.
Otherwise, the invocation of the ZOLOZ Connect checkresult API fails. Check the error code and message for more information about the possible reasons.

Common error codes

For the full list of common error codes, see the Common error codes section in the Error handling topic.

API-specific error codes

The following table shows the possible error codes that are specific for the Connect checkresult API.

resultCode	resultSatus	Description
SUCCESS	S	The API call is successful.
INVALID_ARGUMENT	F	Input parameters are invalid. For more information about which parameter is invalid, check the result message or the related log.
SYSTEM_ERROR	F	Other internal errors. For more information about the error details, check the result message or the related log.
NOT_SAME_PERSON	F	Face verification failed. Possible reasons include: Face comparison score is below the threshold. Fraud or high-risk behavior detected. Deeper analysis failed.
UNABLE_GET_IMAGE	F	Enrolled image is not available or invalid.
PROCESSING	F	The face verification is still in processing.

Sample

Request Sample

The following sample shows what a request that the merchant server sends looks like.

copy

copy
{
    "bizId": "2017839040588699",
    "transactionId": "G006600016CN20190114000000009572520355",
}

Response Sample

The following sample shows what a response that the ZOLOZ server returns looks like.

copy
{
    "result": {
        "resultCode": "SUCCESS",
        "resultMessage": "Success",
        "resultStatus": "S"
    },
    "connectResult":"Success",
    "extFaceInfo": {
        "aliveImage": "#ALIVE_FACE_BASE64_CONTENT#",
        "refImage": "#REFERENCE_FACE_BASE64_CONTENT#",
        "faceScore": 89.1,
        "faceAttack": false,
        "deeperResult":"Success",
        "deeperResultDescription":""
    }
}

More information

ExtFaceInfo

The following table shows the fields that can be specified in the ExtFaceInfo data model.

Field name	Data type	Description
aliveImage	String	The face selfie image, which is encoded in base64. This field is specified only when the face verification process runs successfully.
refImage	String	The face enrolled image, which is encoded in base64. This field is specified only when the face verification process runs successfully.
faceScore	Double	Specifies the score that indicates a result of comparing the live face (selfie) against the enrolled face. Required if the face verification process runs successfully. The value of this field is in the range of 0-100.
faceAttack	Boolean	Specifies whether the face selfie image is detected as a fake face attack by using the face liveness check algorithm. If the image is not a fake face attack, the value of `false` is returned; otherwise, the value of `true` is returned.
deeperResult	String	Optional. Returned the deeper face detection result. The following values will be returned: `Success`: The deeper face detection has passed. No AIGC attack risk has been detected. `Failure`: The deeper face detection has failed. AIGC attack risks have been detected.
deeperResultDescription	String	Optional. Specifies the detail descriptions of the deeper face detection result when `deeperResult` returned `Failure`.