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.

When the App SDK mode is used, its value comes 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.

When H5 mode is used, simply set the value as MOB_H5. 

flowType

String

32

-

Required. Specifies the type of the identity proofing flow. The following values are supported:

REALIDLITE_KYC : specify this value when the App SDK mode is used. 

H5_REALIDLITE_KYC : specify this value when the H5 mode is used. 

docType

String

16

-

Required. Type of document.
For example, if the document to be uploaded is a passport, set the value of this attribute to 00000001003. The value of this field must not be null or an empty string. For the document types that are supported by Real ID, see Document types supported and OCR results returned. 

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

null

Optional. Specifies the business scene for data analysis purposes. 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 purposes; for example, registration, withdraw, topUp, transfer, changePassword.

serviceLevel

String

32

REALID0001

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

• REALID0001 : If this value is set, the ZOLOZ SDK will ask users to manually take photos of the identity document. The ZOLOZ server performs basic spoofing checks, and basic liveness checks using the blink detection method.
• REALID0002 : If this value is set, the ZOLOZ SDK automatically scans the identity document. The ZOLOZ server performs advanced spoofing checks, and basic liveness checks using the blink detection method. 
• REALID0003: If this value is set, the ZOLOZ SDK automatically scans the identity document. The ZOLOZ server performs advanced spoofing checks, and performs a liveness check using any of the 2 user actions below randomly. This service level is only for native SDK.

• Multi-action detection methods include: Blink, mouth open, head up, head down, head shakes (left), head shakes (right) 

• REALID0004: If this value is set, the ZOLOZ SDK automatically scans the identity document even when at an angle. The ZOLOZ server performs basic spoofing checks, and basic liveness checks using the blink detection method.
• REALID0009: If this value is set, the ZOLOZ SDK automatically scans the identity document. ZOLOZ performs an advanced spoofing checks and performs a liveness check using the blink detection method. This service level provides the ability to capture closed-eye images for native SDK.
• REALID0011: If this value is set, the ZOLOZ SDK automatically scans the identity document. ZOLOZ performs an advanced spoofing checks and performs a liveness check using the blink detection method. This service level provides the ability to capture closed-eye images for web SDK.
• REALID0012: If this value is set, the ZOLOZ SDK automatically scans the identity document. ZOLOZ performs basic spoofing checks and performs a liveness check using the blink detection method. This service level is only 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.
• STANDARD_VC_CLOSED: You can use this operation mode to disable Velocity feature.
• STANDARD_IDN_CLOSED: You can use this operation mode to disable IDN feature.
• STANDARD_VC_IDN_CLOSED: You can use this operation mode to disable Velocity feature and IDN feature.

Note: When the value is set to STANDARD_VC_CLOSED, STANDARD_IDN_CLOSED or STANDARD_VC_IDN_CLOSED, other algorithm capabilities are the same as STANDARD.

Here are the definitions for IDN and Velocity:

• IDN: indicates that a fake attack risk is detected through the ID network check. For example, a face is detected associated with multiple IDs, or an ID is detected associated with multiple faces. For more details, see checkresult |API Reference.
• Velocity: indicates that a fake attack risk is detected through the velocity check. For example, the number of attack (e.g. fake ID or liveness attacks) attempts by the same user (identified by userId, ID number or deviceId) in the past period of time reaches a certain threshold, the velocity check will not allow user further submission until the cooldown period has passed.

pages

String

32

all pages of the specified document

Optional. Specifies the document page numbers to scan and upload, separated by commas. E.g. "1" (scan the first page), "1,2" (scan the first and second page)

pageConfig

PageConfig

null

Optional. Specifies the configuration settings for the embedded H5 page. For more information, see pageConfig. 

h5ModeConfig

H5ModeConfig

null

Optional. Specifies the configuration settings for H5 Real ID flow. Set this field when the H5 mode is specified with the flowType filed as H5_REALIDLITE_KYC. For more information, see h5ModeConfig. 

productConfig

ProductConfig

null

Optional. Specifies finer controls for the Real ID product. For more information, see productConfig.

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 identity proofing process. This ID will be used as an input parameter for the Real ID checkresult API request.

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

clientCfg

String

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

resultCode

resultStatus

Description

SUCCESS

S

The API call is successful.

F

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

F

The user account is blacklisted by the risk engine.

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. 

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. 

Field name

Data type

Max length

Description

urlFaceGuide

String

256

Optional. Specifies the URL to the face guide page, which is an H5 prompt page that can be customized to guide users during face scanning. For example, http://url-to-face-guide-page.html. 

Field name

Data type

Max length

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

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. 

locale

String

16

en

Optional. Language of the web page, currently supports: en (English) / zh-CN (Simplified Chinese) / zh-HK (Traditional Chinese) / jp (Japanese) / th (Thai) / es (Español) / pt (Portuguese) / fr (French) / id (Indonesian) / de (German) / kr (Korean) / vi(Vietnamese).

isIframe

String

1

N

Optional. If the Web Page needs to be open in Iframe, this parameter should be set as Y. The following values are supported: 

• Y
• N

uiCfg

String

256

null

Optional. Custom UI configurations in the JSON string format. Only supports  titlebarbgcolor, titlebartextcolor, and buttoncolor for now.

For example:"{\"titlebarbgcolor\":\"#ffffff\",\"titlebartextcolor\":\"#000000\",\"buttoncolor\":\"#3696fd\"}".

allowDegradation

String

1

N

Optional. If degraded mode is allowed, this parameter should be set to Y. The following values are supported:

• Y: Degraded mode is allowed.
• N: Degraded mode is not allowed.

Notes:

• When this parameter is set to Y, the user can choose to enter degraded mode if Zoloz detects that the user's browser does not support Web SDK. Upon confirmation of entering degraded mode, Zoloz will initiate the native camera system for taking photos.
• Degraded mode may pose a higher risk. The highest eKYC result of transactions from this source is Pending, which requires a second check.

docFrontPageGuideUrl

String

128

null

Optional. Specifies the URL of the first page of the document guide page in downgrade mode. This is an H5 prompt page that can be customized to guide users in collecting the first page of the document. If this parameter is not provided, the default page will be displayed.

docBackPageGuideUrl

String

128

null

Optional. Specifies the URL of the second page of the document guide page in downgrade mode. This is an H5 prompt page that can be customized to guide users in collecting the second page of the document. If this parameter is not provided, the default page will be displayed.

facePageGuideUrl

String

128

null

Optional. Specifies the URL of the face guide page in downgrade mode. This is an H5 prompt page that can be customized to guide users in collecting selfies. If this parameter is not provided, the default page will be displayed.

Field name

Data type

Max length

Description

Notes

cropDocImage

String

1

N

Optional. Specify whether to crop the background of the captured DOC image. Valid values include:

• Y: Return an additional doc image cropped from the original captured doc image

• Note: A second additional doc image may be returned if two sides are captured  i.e. front and back

• N: Default value. Do not crop

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: Default value. Do not crop

landmarkCheck

Array

null

Optional. Specify whether to perform landmark checks within a DOC spoofing check. Landmark checks are only applicable for selected documents. E.g. (MyKad)

An array of supported landmark components needs to be specified if landmark check is expected. To understand the valid values for this field, please refer to DOC spoofing check details.

hologramCheck

Array

null

Optional. Specify whether to perform hologram checks  within a DOC spoofing check. Hologram checks are only applicable for selected documents. E.g. (MyKad)

An array of supported hologram check components needs to be specified if hologram check is expected. To understand the valid values for this field, please refer to DOC spoofing check details.

pageInfoCheck

Array

null

Optional. Specify whether to perform information checks within a DOC spoofing check. information checks are only applicable for selected documents.

An array of supported information check components needs to be specified if information check is expected. To understand the valid values for this field, please refer to DOC spoofing check details.

preciseTamperCheck

String

1

N

Optional. Specify whether to perform a precise tamper check. Precise tamper checks are only applicable for selected documents. The following values are supported: 

• Y: Yes
• N: Do not perform a precise tamper check

allowExpiredDocument

String

Different document types have different default values, which are set as follows:

• Y: For all documents except Passport (docType=00000001003)
• N:  For Passport (docType=00000001003)

Optional. Specifies whether expired documents are allowed. The following values are supported: 

• Y: Allow expired documents.
• N: Pause Real ID process when an expired document is detected.

Note: Invalid values will fall back to the default option and pause the Real ID process when an expired document is detected.

docUiType

String

20

• Native SDK: 2
• Web SDK: 1

Optional. This parameter refers to methods for taking ID photos. The values are as follows:

• 1: Self-capture. Users need to manually take ID photos,  and it only has basic anti-spoofing capabilities.
• 2: Deep-scan, only for Native SDK. ZOLOZ SDK automatically aligns and captures ID photos, and it has advanced anti-spoofing capabilities such as intercepting printed color images.
• 3: Auto-scan, only for Web SDK. ZOLOZ SDK automatically aligns and captures ID photos, and it only has basic anti-spoofing capabilities.
• 4: Trace-scan, only for Native SDK. ZOLOZ SDK automatically captures ID photos when the document is detected within the camera range. It can improve user experience, but  it only has basic anti-spoofing capabilities.
• 5: Multi-angle, only for HKID in Web SDK. Users need to take two document photos from different angles. For the first photo, make the camera directly face the ID document and captures its photo. For the second,  incline the ID document 30° against the camera and capture its photo.

The following parameters take precedence over serviceLevel and operationMode. If any of these parameters is passed in, the default values of other parameters take effect. In this case, serviceLevel and operationMode do not take effect, even if their values are passed in.

• docUiType
• spoofMode
•  livenessMode
• antiInjectionMode
• actionCheckItems
• actionRandom
• actionFrame
• riskMode
• idnThreshold

spoofMode

String

10

STANDARD

Optional. This parameter refers to document anti-spoofing levels, defined as follows:

• CLOSED: All algorithms are not applied. You can use this anti-spoofing 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: Reserved value, not currently supported for use.
• STRICT: Reserved value, not currently supported for use.

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

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. 

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.

riskMode

String

10

STANDARD

Optional. This parameter refers to multi-dimensional risk control rule verification in RealID. It is used to intercept suspicious transactions. The values are as follows:

• CLOSED: All algorithms about risk detection are not applied. You can use this risk 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 risk detection mode in low-risk scenarios.
• STRICT: A relatively stricter level is applied. You can use this risk detection mode in high-risk scenarios.

idnThreshold

Integer

3

Optional. This parameter is used to check transactions in which one user uses different ID documents or one ID document is used  by different users. When the number of such transactions (from different userId) exceeds the threshold, the current transaction will be intercepted.  

Any integer larger than 0 is supported. 

faceAttributeCheck

faceAttributeCheck

null

Optional. This parameter is used to specify whether to detect face attributes and control whether to retry when face attributes are detected.

The faceAttributeCheck parameters take precedence over livenessMode.

For example, if occlusionCheck.detectOpen is set to N, even livenessMode is set to STRICT, the face occlusion check is disabled. For details, please refer to the faceAttributeCheck.

Field name

Data type

Max length

Description

occlusionCheck

faceAttributeDetails

null

Optional. Specify whether to detect face occlusion attributes. For details, please refer to the faceAttributeDetails.

maskCheck

faceAttributeDetails

null

Optional. Specify whether to detect mask attributes. For details, please refer to the faceAttributeDetails.

glassesCheck

faceAttributeDetails

null

Optional. Specify whether to detect glasses attributes. For details, please refer to the faceAttributeDetails.

hatCheck

faceAttributeDetails

null

Optional. Specify whether to detect hat attributes. For details, please refer to the faceAttributeDetails.

Field name

Data type

Max length

Description

detectOpen

String

null

Specify whether to detect face attributes and return its result in checkresult API.

• Y: open the face attribute detection
• N: close the face attribute detection

needRetry

String

null

Specify whether to retry when the specified attribute is detected.

• Y: Require retry when the specified attribute is detected.
• N: No need for retry when the specified attribute is detected.

Note: When needRetry is Y, detectOpen must be set toY.

details

List<String>

null

Specify whether to return additional detailed information of face attributes. Currently only support occlusionCheck. Available options as follows:

• eyesOcclusion: return eyes occlusion result
• noseOcclusion: return nose occlusion result
• mouthOcclusion: return mouth occlusion result
• foreheadOcclusion: return forehead occlusion result
• chinOcclusion: return chin occlusion result
• cheekOcclusion: return cheek occlusion result

Notes:

• When details parameter is not empty, detectOpen must be set to Y.
• When details parameter is provided, overall and particular attribute results will be returned in checkresult API.

Date

Change log

28 March, 2024

A new parameter, faceAttributeCheck, is added in productConfig.

22 November, 2023

Added new fields for the productConfig parameter.

22 May, 2022

A new parameter, productConfig, is added in the request. 

8 September，2020

• Two more types of identity documents are supported: Malaysia MyKad and Macau identity card.
• A new parameter, h5ModeConfig, is added in the request. 

9 June, 2020

A new parameter, pageConfig, is added in the request. 

27 December, 2019

• The parameter productLevel is renamed to serviceLevel, and the related description is updated. 

20 December, 2019

The following two request parameters are added:

• productLevel
• operationMode 

06 December, 2019

Released.