VideoVerify - Initialize API

2026-06-25 06:23

Important Notice:

All request and response parameters are strictly subject to the official API documentation.
The API response may contain fields not defined in the documentation. These fields are for internal debugging purposes only and are not guaranteed to be stable or compatible. Do not rely on these fields in production environments. ZOLOZ reserves the right to modify or remove these fields at any time without prior notice.

Overview

API URL: /api/v1/zoloz/videoverify/initialize
API Description: Used to initialize a VideoVerify transaction. Upon successful invocation, the system returns a unique transactionId and the clientCfg required for the client to start the SDK.

Note: This API is not idempotent. Each new business process must use a new bizId to call the Initialize API. Do not reuse the same bizId.

Request Parameters

Field Name	Data Type	Max Length	Mandatory	Default Value	Description	Example Value
bizId	String	32	true	-	A unique business ID on the merchant side for tracking purposes. It is recommended to map it to a business order, application ID, or serial number. Note: ZOLOZ does not validate the uniqueness of this value; the merchant side must ensure its uniqueness.	"VV2026060500000001"
metaInfo	String	512	true	-	The meta information about the SDK and the user's device. In native app mode, this value is returned by the ZOLOZ SDK. Please pass it directly without any modification.	"{\"apdidToken\":\"xxx\",\"appName\":\"com.example.app\",\"appVersion\":\"1.0.0\",\"bioMetaInfo\":\"3.46.0:0,2\",\"deviceModel\":\"iPhone13,3\",\"deviceType\":\"ios\",\"osVersion\":\"iOS 26.1\"}"
userId	String	64	true	-	A user identifier on the merchant side, such as a user ID, phone number, or email. It is recommended to hash or desensitize this value before passing.	"hash_user_001"
sceneCode	String	64	false	null	A business scenario code used to distinguish data performance across different scenarios, e.g., `login`, `riskVerify`, `payment`, `changePassword`.	"changePassword"
productConfig	ProductConfig	-	false	null	Fine-grained configuration parameters for the VideoVerify product. For configurable items, see ProductConfig.	{ "riskMode": "STANDARD" }

ProductConfig

Field Name

Data Type

Max Length

Mandatory

Default Value

Description

Example Value

riskMode

String

false

STANDARD

The multi-dimensional risk control cooldown rule verification in VideoVerify, used to intercept suspicious transactions. Supported values:

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"

Response Parameters

Field Name	Data Type	Description	Example Value
result	Result	Required. The result of the API request, including the operation status, result code, and message.	{ "resultStatus": "S", "resultCode": "SUCCESS", "resultMessage": "Success" }
transactionId	String	Optional. The unique transaction ID generated by the ZOLOZ server for this 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.	"G006600016CN2019011400000000957252****"
clientCfg	String	Optional. The client configuration information, including parameters about the SDK connection and behavior. Returned only when the `result.resultStatus` field is `S`.	"..."

Result

API-Common Result Codes

For the full list of common error codes, see the Common error codes section in the Error handling topic.

API-Specific Result Codes

The following table lists result codes specific to the VideoVerify 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 current device type is not supported.
OS_NOT_SUPPORT	F	The current operating system is not supported.
SDKVERSION_NOT_SUPPORT	F	The current SDK version is not supported.
INVALID_ARGUMENT	F	Input parameters are invalid. For more information about which parameter is invalid, check the result message.
SYSTEM_ERROR	F	Internal system error. For details, please check the returned `resultMessage`.

Sample

Request Sample

copy
{
    "bizId": "VV2026060500000001", 
    "metaInfo": "{\"apdidToken\":\"xxx\",\"appName\":\"com.example.app\",\"appVersion\":\"1.0.0\",\"bioMetaInfo\":\"3.46.0:0,2\",\"deviceModel\":\"iPhone13,3\",\"deviceType\":\"ios\",\"osVersion\":\"iOS 26.1\"}", 
    "userId": "hash_user_001", 
    "sceneCode": "loanGuarantee", 
    "productConfig": {
        "riskMode": "STANDARD"
    }
}

Response Sample

copy
{
    "result": {
        "resultStatus": "S", 
        "resultCode": "SUCCESS", 
        "resultMessage": "Success"
    }, 
    "transactionId": "G006600016CN2019011400000000957252****", 
    "clientCfg": "..."
}