Connect APIs

2021-04-15 13:47

API Overview

Please note these APIs are exposed via ZOLOZ Gateway. Please refer to the ZOLOZ Gateway Document for the correct way of invocation.

API Name	Description
v1.zoloz.connect.initialize	This will initialize a verification application in ZOLOZ with a unique transaction ID, which shall be used in all the subsequent interactions with ZOLOZ for the same application.
v1.zoloz.connect.checkresult	This is for your server side to retrieve the verification result no matter the verification process is completed successfully or not.
v1.zoloz.connect.enroll	This is used to enroll a face image of one user for subsequent usage of connect.

Initialize

Request Sample

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\"
      }"
}

Request Fields Specification

Name	Type	Max Length	Mandatory	Description	Sample Value
bizId	String	32	Yes	Uniquely generated, globally unique business ID, for tracing. e.g. Sequence ID from DB.	2017839040588699
metaInfo	String	512	Yes	Meta info from client.	<metaInfoFromClient>
userId	String	64	Yes	Merchant user id. Must be the same as enrolled information. Either userId or certInfo, one of them must be in the request.	2305940069977
sceneCode	String	64	No	Business scene for data analysis purpose, no real business impact.If you want to distinguish the data performance of different scenarios,we suggest setting sceneCode to different value.It is recommended to name sceneCode's value according to business purpose.For example: login, riskVerify, payment, changePassword.	changePassword
serviceLevel	String	32	No	The service level, check following table for details.	CONNECT0002

The value range of "serviceLevel" at business level

Response Sample

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

Response Fields Specification

Name	Type	Mandatory	Description	Sample Value
result	Result	Yes	API result.
result.resultStatus	String	Yes	Result status. "S": Successful "F": Failed.	S
result.resultCode	String	Yes	Result code. Refer to the table below for more information.	SUCCESS
result.resultMessage	String	Yes	More information to describe the result code.	success
transactionId	String	No	Unique ID that used to start Connect SDK in client side. Server side need to pass this to calling client for further processing. It will be provided when error is not on client side. For example, invalid arugment won't have transactionId.	G006600016CN20190114000000009572520355
clientCfg	String	No	Client config to be used by Zoloz SDK.

The value range of "resultCode" at business level:

resultCode	Description
SUCCESS	Success.
UNABLE_GET_IMAGE	No reference source is found (caused by attempting to verify before enroll).
HIGH_RISK	The account is cooled down by the risk engine.
ACCOUNT_SERVICE_SUSPEND	The account is blacklisted by the risk engine.
DEVICE_NOT_SUPPORT	The device is not supported.
OS_NOT_SUPPORT	The operating system version is not supported.
SDKVERSION_NOT_SUPPORT	The APP version is not supported.
INVALID_ARGUMENT	Invalid argument.
SYSTEM_ERROR	System error.

CheckResult

Request Sample

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

Request Fields Specification

Name

Type

Max Length

Mandatory

Description

Sample Value

bizId

String

Yes

Uniquely generated, globally unique business ID, for tracing. e.g. Sequence ID from DB.

2017839XXXXXX699

transactionId

String

Yes

Unique ID that returned from initialize api.

when error is client side

like invalid argument, we won't return txnId

G006600016CN20190114000000009572520355

Response Sample

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

Response Fields Specification

Name	Type	Mandatory	Description	Sample Value
result	Result	Yes	API result.
result.resultStatus	String	Yes	Result status at system level. "S" or "F". "S" stands for success and "F" stands for failure.	S
result.resultCode	String	Yes	Detailed result code. Refer to the table below for more information.	SUCCESS
result.resultMessage	String	Yes	Result details. Explanation to result code.	Success
extFaceInfo	ExtFaceInfo	No	Detailed information. Refer to the table below for details.

ExtFaceInfo Specification

Name	Fields Key	Type	Description	Sample Value
extFaceInfo	aliveImage	String	Alive face image in base64 format, only presents when retCode equals SUCCESS or NOT_SAME_PERSON.
	refImage	String	Referenced face image in base64 format, only presents in a verification flow where retCode equals SUCCESS or NOT_SAME_PERSON.
	faceScore	double	Face matching similarity, only presents in a verification flow where retCode equals SUCCESS or NOT_SAME_PERSON.	89.1
	faceAttack	boolean	Attack detected, only presents when retCode equals SUCCESS or NOT_SAME_PERSON. Possible values will be: true/ false.	true

The value range of "resultCode" at business level:

resultCode	Description
SUCCESS	Success.
INVALID_ARGUMENT	Invalid argument.
SYSTEM_ERROR	System error.
NOT_SAME_PERSON	Authentication fails because similarity score is lower than threshold or spoofing behavior/high risk behavior is detected.
UNABLE_GET_IMAGE	Enrolled image is not available or invalid.
PROCESSING	The authentication is still in processing.

Enroll

Request Sample

copy
{
    "bizId":"2017839040588699",
    "userId":"merchant side user id", 
    "base64ImageContent":"xxxxxxxxxxxxxxxxx"
}

Request Fields Specification

Name	Type	Max Length	Mandatory	Description	Sample Value
bizId	String	32	Yes	Uniquely generated, globally unique business ID, for tracing. e.g. Sequence ID from DB.	2017839040588699
userId	String	64	Yes	Merchant user id. Must be the same as enrolled information. Either userId or certInfo, one of them must be in the request.	2305940069977
base64ImageContent	String		Yes	Image content using base64 encode

Response Sample

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

Response Fields Specification

Name	Type	Mandatory	Description	Sample Value
result	Result	Yes	API result.
result.resultStatus	String	Yes	Result status. "S": Successful "F": Failed.	S
result.resultCode	String	Yes	Result code. Refer to the table below for more information.	SUCCESS
result.resultMessage	String	Yes	More information to describe the result code.	success
transactionId	String	No	Unique ID that used to for this enroll request. It will be provided when if error is not on client side. For example invalid argument won't have transactionId.	G006600016CN20190114000000009572520355

The value range of "resultCode" at business level:

resultCode	Description
SUCCESS	Success.
UNABLE_GET_IMAGE	Cannot extract face feature from requested image.
INVALID_ARGUMENT	Invalid argument.
SYSTEM_ERROR	System error.

serviceLevel	UI	Description
CONNECT0001	Garfield	This level has basic liveness detection ability. Because Garfield doesn't require user to jump to a new page, which makes less user drop off, it is usually used in the scenarios which require high pass rate
CONNECT0002	Cherry(Blink)	Default level. This level has basic anti-spoofing ability and basic liveness detection ability
CONNECT0003	Cherry(Multi-action)	This level has advanced anti-spoofing ability and basic liveness detection ability