checkresult

2024-04-17 17:34

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.

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	The face verification fails because similarity score is lower than threshold or spoofing behavior/high risk behavior is detected.
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"
    },
    "extFaceInfo": {
        "aliveImage": "#ALIVE_FACE_BASE64_CONTENT#",
        "refImage": "#REFERENCE_FACE_BASE64_CONTENT#",
        "faceScore": 89.1,
        "faceAttack": false
    }
}

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.