Field Name

Data Type

Max Length

Required

Default Value

Description

Example

bizId

String

32

Yes

-

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.

2026053000001

metaInfo

String

512

Yes

-

The meta information about the SDK and the user's device. This value is returned by the ZOLOZ SDK in JSON string format.

Note: Do not modify the returned value; pass it through directly. When H5 mode is used, set this value to MOB_H5.

MOB_H5

flowType

String

32

Yes

-

Specifies the type of the identity verification flow. Supported values:

• REUSABLE_REALIDLITE_KYC: Native SDK mode.
• H5_REUSABLE_REALIDLITE_KYC: H5 mode.

REUSABLE_REALIDLITE_KYC

userId

String

64

Yes

-

The Recipient-side user ID or other identifier that can be used to identify a specific user. It is strongly recommended to pre-desensitize sensitive identifiers such as phone numbers or email addresses (e.g., by hashing).

u_recipient_88001

shareToken

String

64

Yes

-

The one-time sharing credential generated by the Donor, which can only be used by the current Recipient.

Ks3LpQa9R7vN2bWxYz8Hf7pK_demo_token_43_chars

acceptedDocTypes

List

200

No

null

Specifies the list of document types acceptable to the Recipient, used to filter the Donor's documents. This parameter can be used alone or in combination with acceptedDocCountryCodes.

• Multiple values in the list are in an OR relationship.
• If not passed or passed as an empty list, document type is not restricted.
• If the Donor's document type is missing or not in the specified list, the API returns DONOR_DATA_NOT_ACCEPTABLE.

For supported document types, see Document types supported and OCR results returned.

["00000001003"]

acceptedDocCategories

List

50

No

null

Specifies the document categories acceptable to the Recipient, used to filter the Donor's documents. This parameter can be used alone or in combination with acceptedDocCountryCodes.

• The supported document categories are as follows:

• PASSPORT
• DRIVING_LICENSE
• ID_CARD
• RESIDENCE_PERMIT
• VISA

• Multiple values in the list are in an OR relationship.
• If not passed or passed as an empty list, document category is not restricted.
• If the Donor's document category is missing or not in the specified list, the API returns DONOR_DATA_NOT_ACCEPTABLE.

["PASSPORT"]

acceptedDocCountryCodes

List

50

No

null

Specifies the list of countries or regions acceptable to the Recipient for the Donor's document. Supports three-letter country codes conforming to the ISO 3166-1 alpha-3 standard (e.g., CHN, PHL, HKG).

Usage methods:

• When acceptedDocCountryCodes is used independently: It indicates that the document type passed in belongs to a specific country or region.
• When acceptedDocCountryCodes and acceptedDocCategories are used together, the system applies the intersection of both parameters. This indicates that the document type list is restricted to documents from a specific country.
  For example: acceptedDocCategories=ID_CARD and DRIVING_LICENSE, acceptedDocCountryCodes=PHL, This means that only Philippine ID cards and driver's license are allowed to pass through. Otherwise, the system will prompt a document type error.
• When acceptedDocCountryCodes and acceptedDocTypes are used together, the system applies the intersection of both parameters. This indicates that the document type list is restricted to documents from a specific country.
  Note:

• The acceptedDocTypes parameter must include a universal passport (00000001003 or 00000001006) to be used in combination; otherwise, the request will be blocked by the system.
• acceptedDocCountryCodes must cover the country scope in the acceptedDocTypes list being passed in. Otherwise, the system will block the request.

Note:

• Multiple values in the list are in an OR relationship.
• If not passed or passed as an empty list, country or region is not restricted.
• If the Donor's document country or region is missing or not in the specified list, the API returns DONOR_DATA_NOT_ACCEPTABLE.

["HKG"]

sceneCode

String

64

No

null

A business scenario code, used to distinguish data performance across different business scenarios.

ONBOARDING_REUSE

productConfig

ProductConfig

-

No

null

Face liveness and risk control configuration for Reusable RealID. See the ProductConfig Field Description section for details.

{ "livenessMode":"STANDARD" }

pageConfig

PageConfig

-

No

null

SDK page configuration. See the PageConfig Field Description section for details.

{ "urlFaceGuide":"https://example.com/face-guide" }

h5ModeConfig

H5ModeConfig

-

Required in H5 mode

-

H5 Reusable RealID configuration. This field is required when flowType is H5_REUSABLE_REALIDLITE_KYC. See the H5ModeConfig Field Description section for details.

{ "completeCallbackUrl":"https://example.com/complete", "interruptCallbackUrl":"https://example.com/interrupt" }

envData

Map<String, Object>

-

No

null

SDK runtime environment parameters. Currently only supports envName, used to specify the runtime environment for the SDK. If not passed, the default environment of the current site is used.

{ "envName":"default" }

deviceId

String

-

No

null

The user device identifier in H5 mode.

ZLZ8a402976-d30c-475a-a569-40978b38e8eb

clientIp

String

-

No

null

The client IP address of the user device in H5 mode.

203.0.113.10

wirelessConfigGroup

String

32

No

null

SDK wireless configuration group, used to select the corresponding SDK wireless configuration for different business scenarios.

default

Field Name

Data Type

Max Length

Required

Default Value

Description

Example

livenessMode

String

10

No

STANDARD

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.

STANDARD

actionCheckItems

List<String>

-

No

FACEBLINK

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.
• NOACTION: No action

Notes：

• NOACTION is mutually exclusive with other actions and cannot be set simultaneously. If NOACTION is set, the actionRandom, actionRandomNumber and actionFrame parameters become ineffective.
• To ensure a better user experience, it is recommended to select only one action and avoid using two or more actions simultaneously.
• Each action type can be passed only once; do not pass the same action type repeatedly.

["FACEBLINK","HEADLOWER"]

actionRandom

String

1

No

N

Specifies whether the order of action detection is random. Supported values:

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

Y

actionRandomNumber

String

-

No

null

Defines the number of random action checks from the customer-specified action list (actionCheckItems).

Value range: Must be a positive integer, and 0 < actionRandomNumber ≤ the total number of actions specified in actionCheckItems.

Notes:

• The priority of the actionRandomNumber parameter is higher than actionRandom. If both are provided, actionRandomNumber takes precedence.
• When actionRandomNumber is empty and actionRandom = Y, perform random checks on all actions in actionCheckItems.
• When actionRandomNumber is empty and actionRandom = N (or is empty), perform checks in the order specified in actionCheckItems.

1

actionFrame

List<String>

-

No

null

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. And ensure that the actionCheckItems parameter includes FACEBLINK; otherwise, the blink detection feature will fail to activate.
• MULTIACTIONS: Capture one frame for each client-side action and return the frames. If you set this value but the client detects no action, the action frame content in the response is empty.

["EYECLOSE"]

colorFlash

String

-

No

N

Enable color-based liveness detection.

• Y: Enable the color-based liveness detection feature.
• N: Disable the color-based liveness detection feature.

Note:

• This feature is supported only by mobile Native SDK (iOS and Android) and Web SDK. It is not supported on HarmonyOS SDK and PC devices.
• If multi-action detection is configured, the color-based liveness detection process will be executed after the completion of the multi-action process.

Y

riskMode

String

10

No

STANDARD

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

• CLOSED: Disable risk control cooldown rules. This level is applicable to testing scenarios where the testing process is not affected by risk control rules.
• 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.

STANDARD

faceAttributeCheck

FaceAttributeCheck

-

No

null

Optional. Face Attribute Detection. For details, see FaceAttributeCheck.

Note: 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.

{

"occlusionCheck": {

"details": [

"eyesOcclusion",

"noseOcclusion",

"mouthOcclusion",

"foreheadOcclusion",

"chinOcclusion",

"cheekOcclusion"

],

"detectOpen": "Y",

"needRetry": "Y"

},

"maskCheck": {

"detectOpen": "Y",

"needRetry": "N"

},

"glassesCheck": {

"detectOpen": "Y",

"needRetry": "N"

},

"hatCheck": {

"detectOpen": "Y",

"needRetry": "N"

}

}

cropFaceImage

String

1

No

N

Specifies 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

Y

Field Name

Data Type

Max Length

Required

Default Value

Description

Example

occlusionCheck

FaceAttributeDetails

-

No

null

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

{

"details": [

"eyesOcclusion",

"noseOcclusion",

"mouthOcclusion",

"foreheadOcclusion",

"chinOcclusion",

"cheekOcclusion"

],

"detectOpen": "Y",

"needRetry": "Y"

}

maskCheck

FaceAttributeDetails

-

No

null

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

{

"detectOpen": "Y",

"needRetry": "N"

}

glassesCheck

FaceAttributeDetails

-

No

null

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

{

"detectOpen": "Y",

"needRetry": "N"

}

hatCheck

FaceAttributeDetails

-

No

null

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

{

"detectOpen": "Y",

"needRetry": "N"

}

Field Name

Data Type

Max Length

Required

Default Value

Description

Example

detectOpen

String

1

Yes

null

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

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

"Y"

needRetry

String

1

Yes

null

Specifies whether to allow the user to retry when the specified attribute is detected. Supported values:

• Y: Allow retry. When needRetry is Y, detectOpen must also be Y.
• N: Do not allow retry. Even if needRetry is N, the eKYC flow may still prompt for a retry due to poor face quality.

"Y"

details

List<String>

-

No

null

A list of specific occlusion parts for which detailed results should be returned. Currently, this only supports returning detailed results for 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

Note:

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

[

"eyesOcclusion",

"noseOcclusion",

"mouthOcclusion",

"foreheadOcclusion",

"chinOcclusion",

"cheekOcclusion"

]

Field Name

Data Type

Max Length

Required

Default Value

Description

Example

urlFaceGuide

String

256

No

null

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.

Note:

• On PC, the Face Guide page is a non-customizable standard template. This parameter allows you to assign a custom page for the mobile mode.
• If you want to hide the face guide page's title bar, see How do I hide the face guide page's title bar in Native SDK?

https://example.com/face-guide

Field Name

Data Type

Max Length

Required

Default Value

Description

Example

state

String

128

No

the value of transactionId

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.

order_2026053000001

completeCallbackUrl

String

128

Yes

-

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

https://example.com/complete

interruptCallbackUrl

String

128

Yes

-

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

https://example.com/interrupt

locale

String

16

No

en

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)

zh-CN

isIframe

String

1

No

N

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

• Y
• N

Y

uiCfg

String

256

No

null

Custom UI Configuration in JSON String Format. Supports the following fields:

• titlebarbgcolor
• titlebartextcolor
• buttoncolor
• isDesktop: Indicates whether the document capture mode is initialized from the PC side.

• Y: Initialized from the PC side. When isDesktop is Y, serviceLevel only supports REALID0001, and docUiType only supports 1; otherwise, the system will return INVALID_ARGUMENT.
• N: Initialized from the mobile side; use the mobile Web SDK collection process. The default value is N.

{\"titlebarbgcolor\":\"#ffffff\",\"titlebartextcolor\":\"#000000\",\"buttoncolor\":\"#3696fd\",\"isDesktop\":\"Y\"}

allowDegradation

String

1

No

N

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.

Y

facePageGuideUrl

String

128

No

null

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.

"http://xxx.html"

Field Name

Data Type

Always Returned

Description

Example

result

Result

Yes

The API request result, which contains the result status, result code, and result message.

{

"resultStatus": "S", "resultCode": "SUCCESS", "resultMessage": "Success"

}

transactionId

String

No

The unique transaction ID generated by ZOLOZ for this Reusable RealID identity verification process.

Note: The system will only return the transactionId after the transaction enters the processing stage. If an error occurs before the transaction begins processing, the system will not return a transactionId. This includes, but is not limited to, the following situations:

• Invalid request parameters, such as incorrect input format or missing required parameters.
• The request fails to reach the server successfully, such as due to network issues or gateway failures.
• The request is denied due to system rate limiting.

G000000005FID2020030400000000000157****

clientCfg

String

No

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

API call successful.

TOKEN_NOT_FOUND

F

The shareToken does not exist, has been used, has expired, or is not available for the current Recipient.

DONOR_DATA_UNAVAILABLE

F

The Donor's shareable identity data does not exist or is currently unavailable.

DONOR_DATA_NOT_ACCEPTABLE

F

The Donor's document does not meet the Recipient's filtering criteria configured in acceptedDocTypes, acceptedDocCategories, or acceptedDocCountryCodes, or the document has expired.

PARTNERSHIP_NOT_ACTIVE

F

The Reusable RealID partnership between the Donor and the Recipient is not active or has been suspended.

HIGH_RISK

F

High risk detected. The user account has been frozen by the risk engine.

ACCOUNT_SERVICE_SUSPEND

F

The user account has been blacklisted by the risk engine.

DEVICE_NOT_SUPPORT

F

The current device type is not supported.

OS_NOT_SUPPORT

F

The operating system of the current device is not supported.

SDKVERSION_NOT_SUPPORT

F

The current ZOLOZ SDK version is not supported.

INVALID_ARGUMENT

F

Invalid input parameters. Possible causes include missing required parameters, field length exceeded, or unsupported fields being passed. For detailed error information, check the returned resultMessage.

SYSTEM_ERROR

F

Internal system error. For error details, check the returned resultMessage.