initialize

POST/api/v1/zoloz/facecapture/initialize

The ZOLOZ Face Capture initialize API is used to initialize the face capture 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

Default Value

Description

bizId

String

32

-

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

Note: The ZOLOZ server does not perform uniqueness checks 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 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.  Set to "MOB_H5" if it is in H5 mode.

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. 

h5ModeConfig

H5ModeConfig

null

Optional. Specifies the configuration settings for H5 mode. For more information, refer below to the h5ModeConfig section

serviceLevel

String 

32

FACECAPTURE0002

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

  • FACECAPTURE0001: If this value is set, ZOLOZ uses a more flexible way to do face liveness verification, and it has to work together with current level set in the system's operationMode for determination.
  • FACECAPTURE0002If this value is set, the ZOLOZ server performs a liveness check with the blink detection method used.
  • FACECAPTURE0003If this value is set, the ZOLOZ server performs a liveness check with any 2 user actions used randomly.
    • Multi-action detection methods include:  Blink, mouth open, head up, head down, head shakes (left), head shakes (right) 
  • FACECAPTURE0005If this value is set, the ZOLOZ server performs a liveness check with the blink detection method used. This service level provides the ability to capture closed-eye images for native SDK.
  • FACECAPTURE0010If this value is set, the ZOLOZ server performs a liveness check with the blink detection method used. This service level provides the ability to capture closed-eye images for web SDK.

operationMode

String

32

STANDARD

Optional. Specifies the operation mode where the identity proofing process runs. The following values are supported:

  • CLOSED: All the algorithms and risk control rules are not applied. You can use this operation mode in the test phase so that the algorithms and risk controls rules do not affect the test process.
  • STANDARD: A standard recommended level is applied. 
  • LOOSE: A relatively looser level is applied. You can use this operation mode in low-risk scenarios.
  • STRICT: A relatively stricter level is applied. You can use this operation mode in high-risk scenarios.

productConfig

ProductConfig 

null

Optional. Specifies finer controls on the Face Capture product. For more information, see productConfig.

Note: If productConfig, serviceLevel and operationMode are set together at the same time, neither the serviceLevel nor the operationMode will take effect. This is due to these parameters being in conflict. Instead, ZOLOZ will only read productConfig. 

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 Capture process. This ID will be used as an input parameter for the Face Capture 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 Face Capture 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 Face Capture initialize 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 initialize API.

resultCode

resultStatus

Description

SUCCESS

S

The API call is successful.

HIGH_RISK

F

High risks are detected. The user account is strategically cooled down 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

For different integration modes, the request structures are a little different. When the face capture process is initiated in the H5 mode, additionally, an object called h5ModeConfig must be specified.

Refer to the following two request samples for the detailed information.

Native Face Capture Request Sample

The following sample shows what a request sent from the merchant server looks like.

copy
{
  "bizId":"test-bizId",
  "metaInfo": "{\"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\"}",
  "userId": "test-userId",
  "productConfig": {
    "livenessMode":"STANDARD",
     "antiInjectionMode":"CLOSED",
    "deeperMode":"CLOSED",
    "actionCheckItems":["FACEBLINK","HEADLOWER"],
    "actionRandom":"Y",
    "actionFrame:":["EYECLOSE"]
  }
}

H5 Face Capture Request Sample

The following sample shows what a request looks like if the face capture process is initiated in the H5 mode.

copy
{
  "bizId":"dummy_bizid_1626180988600",
  "metaInfo":"MOB_H5",
  "userId":"dummy_userid_1626180988600",
  "h5ModeConfig":{
      "completeCallbackUrl":"http://xxx/result.html",
      "interruptCallbackUrl":"http://xxx/result.html"
  },
  "productConfig": {
    "livenessMode":"STANDARD",
   "antiInjectionMode":"CLOSED",
    "deeperMode":"CLOSED",
    "actionCheckItems":["FACEBLINK","HEADLOWER"],
    "actionRandom":"Y",
    "actionFrame:":["EYECLOSE"]
  }
}

Response Sample

The following sample shows what a response returned from the ZOLOZ server looks like.

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

More information

h5ModeConfig

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

Field name

Data type

Max length

Default Value

Description

state

String

128

the value of transactionId

Optional. An identifier that is used to recover the customer's context. You can set this field to any String value. The value is then passed as a parameter when the ZOLOZ SDK calls back to the merchant's application. If the value is not set, the value of the transactionId field is used. 

completeCallbackUrl

String

128

-

Required. Specifies the callback URL where the browser is redirected when the whole identity proofing process is completed. 

interruptCallbackUrl

String

128

-

Required. Specifies the callback URL where the browser is redirected when the process is interrupted. 

isIframe

String

1

N

Optional. If the Web Page need to be open in Iframe, this param should be set as Y.

Supported Value: YN

locale

String

16

en

Optional. Language of the web page, only support: en (English) / id (Indonesian) / fl (Filipino) at the moment. The default language is en. 

uiCfg

String

256

null

Optional. Custom UI configurations in the JSON string format.

Only support isDesktop,

For example:"{\"isDesktop\":\"Y\"}".

productConfig

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

Field name

Data type

Max length

Default Value

Description

livenessMode

String

10

STANDARD

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

  • CLOSED: All algorithms are not applied. You can use this liveness detection mode in the test phase so that the algorithms and risk control rules do not affect the testing process.
  • STANDARD: A standard recommended level is applied.
  • LOOSE: A relatively looser level is applied. You can use this liveness detection mode in low-risk scenarios.
  • STRICT: A relatively stricter level is applied. You can use this liveness detection mode in high-risk scenarios.

antiInjectionMode

String

10

CLOSED

Deprecated field.Optional. Specifies the anti-injection level for injection attack detection. Injection attack detection can effectively resist injection attacks using deepfakes i.e. face-swapping pictures or videos. The following values are supported:

  • CLOSED: All the anti-injection algorithms are not applied. If the business scenario does not require injection attack detection, you do not need to enable it.
  • STANDARD: A standard recommended level is applied.
  • LOOSE: Reserved value, not currently supported for use.
  • STRICT:Reserved value, not currently supported for use.

Note: Enabling injection attack detection will slightly increase false rejection rate and runtime. Please contact ZOLOZ technical support team before turning on this function. 

deeperMode

String

10

CLOSED

Optional. Specifies the Deeper level for AIGC attack detection. For a detailed description of the Deeper detection function, refer to the What is the Deeper. The following values are supported:

  • CLOSED: All capability about Deeper are not applied, e.g. AIGC detection algorithms, terminal risk detection, etc. If the business scenario does not require AIGC attack detection, you do not need to enable it.
  • STANDARD: A standard recommended level is applied.
  • LOOSE: A relatively looser level is applied. You can use this detection mode in low-risk scenarios.
  • STRICT: A relatively stricter level is applied. You can use this detection mode in high-risk scenarios.

Note: Please make sure to purchase the Deeper product before enabling this feature.

actionCheckItems

List<String>

FACEBLINK

Optional. User actions to be detected. For better user experience, it is not recommended to use two or more actions. The following values are supported:

  • FACEBLINK: Requires the user to blink their eyes.
  • MOUTHOPEN: Requires the user to open their mouth once.
  • HEADSHAKE: Requires the user to shake their head. Left or right headshake will be specified for the user to perform.
  • HEADLOWER: Requires the user to lower their head once.
  • HEADRAISE: Requires the user to raise their head once.

actionRandom

String

1

N

Optional. Specifies whether user actions specified in actionCheckItems are in random order to be detected. Valid values include:

  • Y: Random
  • N: Not random, action detection is performed following the order in actionCheckItems.

actionFrame

List<String>

null

Optional. This parameter refers to capturing other frame pictures, defined as follows:

  • EYECLOSE: Set this value to return closed-eye frames collected during the blink detection method.

rearCamera 

String

1

N

Optional. Specifies whether to enable the rear camera. Only WebSDK is supported. Valid values include: 

  • Y: Rear camera enabled.
  • N: Rear camera not enabled.

Note: When set to Y, no action/blinking is supported in the range of user actions that can be detected by the rear camera.

cropFaceImage

String

1

N

Optional. Specify whether to crop the face area of the captured FACE image. Valid values include: 

  • Y: Return an additional face image cropped from the original captured face image.
  • N: Do not crop.
checkDeviceRisk

String

1

N

Optional. This parameter has been obsolete and replaced by deeperMode.

Note: checkDeviceRisk will not be deleted to ensure the compatiblity of APIs. When it is set as Ycheckresult API will continue to return the deviceRisk field, which is not used for business decision making and have no impact on the final result.