Connect APIs

#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, paymentchangePassword.

changePassword

serviceLevel

String

32

No

The service level, check following table for details.

CONNECT0002


The value range of "serviceLevel" at business level

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


#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_SUSPENDThe 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

32

Yes

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

2017839XXXXXX699

transactionId

String

64

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 informationRefer 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.