ZOLOZZOLOZDOCS

initialize

POST /api/v1/zoloz/connect/initialize

The ZOLOZ Connect initialize API is used to initialize the face verification process in ZOLOZ. A unique transaction ID is generated for the process and used in all the subsequent interactions with the ZOLOZ server. This API is not idempotent.

Structure

Request parameters

Field name

Data type

Max length

Description

bizId

String

32

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.

metaInfo

String

512

Required. The meta information about the SDK and the user's device. The value of this field is returned from the ZOLOZ SDK in the JSON string format, for example:

"{\"apdidToken\":\"69b74bfe-bf7f-4d3b-ac59-907ee09e7955\",\"appName\":\"com.zoloz.atomic.client\",\"appVersion\":\"1.0.9\",\"bioMetaInfo\":\"3.46.0:2916352,0\",\"deviceModel\":\"MI 6\",\"deviceType\":\"android\",\"osVersion\":\"9\",\"zimVer\":\"1.0.0\"}".

Note: Do not modify the returned value as it only needs to be passed through directly.  

userId

String

64

Required. Merchant user ID, or other identifiers that can be used to identify a specific user, for example, mobile phone number, email address and so on.  It is strongly recommended to pre-desensitize the value of the userId field, for example, by hashing the value. 

sceneCode

String

64

Optional. Specifies the business scene for data analysis purpose. If you want to distinguish the data performance of different scenes, it is recommended to set the sceneCode field to different values according to your business purpose, for example, login, riskVerify, payment, changePassword.

serviceLevel

String

32

Optional. Specifies the service level for face liveness detection. The following values are supported:

  • CONNECT0001 : It has basic liveness detection ability. The UI doesn't require user to jump to a new page, which makes less user drop off. So it is usually used in the scenarios which require high pass rate.
  • CONNECT0002 : Default value. This level has basic anti-spoofing ability. The ZOLOZ SDK performs anti-spoofing check with the blink detection method.
  • CONNECT0003 : This level has advanced anti-spoofing ability. The ZOLOZ SDK performs anti-spoofing check with the multi action detection method.

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. 

transactionId

String

Optional. A unique transaction ID that is generated by the ZOLOZ server for the face verification process. This ID will be used as an input parameter for the Connect checkresult API request.

Note: when an error occurs during the process, for example, invalid argument, no transaction ID is returned.

clientCfg

String

Optional. The client configuration information, including parameters about SDK connection and behavior. The value of this field is specified only when the result.resultStatus field is "S". 

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.resultStatus is S , the ZOLOZ Connect initialize API is invoked successfully and a unique transaction ID is returned.
  • If the value of the result.resultStatus is F , the invocation of the ZOLOZ Connect initialize API fails. Check the error code and message for more information about the possible reasons. Error codes

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 initialize API.

resultCode

resultStatus

Description

SUCCESS

S

The API call is successful.

UNABLE_GET_IMAGE

F

No reference source is found (caused by attempting to verify before enroll).

HIGH_RISK

F

High risks are detected. The user account is strategically cooled down by the risk engine.

ACCOUNT_SERVICE_SUSPEND

F

The user account is blacklisted by the risk engine.

DEVICE_NOT_SUPPORT

F

The device type is not supported.

OS_NOT_SUPPORT

F

The operating system of the device is not supported. 

SDKVERSION_NOT_SUPPORT

F

The version of the ZOLOZ SDK is not supported. 

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 that is returned and the related log. 

Sample

Request Sample

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

copy
{
    "bizId": "2017839040588699",
    "userId": "merchant side user id",
    "sceneCode": "changePassword",
    "serviceLevel": "CONNECT0002",
    "metaInfo": "{
           \"deviceType\": \"deviceType\",
           \"appVersion\": \"1.0\",
           \"osVersion\": \"7.1.1\",
           \"appName\": \"com.alipay.android.zoloz.company\",
           \"bioMetaInfo\": \"3.37.0:262144,0\",
           \"apdidToken\": \"mock-apdidToken\",
           \"deviceModel\": \"MI 6\",
           \"zimVer\": \"2.0.0\"
      }"
}

Response Sample

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

copy
{
    "result": {
        "resultStatus": "S",
        "resultCode": "SUCCESS",
        "resultMessage": "Success"
    },
    "transactionId":"G006600016CN20190114000000009572520355", 
    "clientCfg": "……"   
}