VideoVerify - Initialize API

2026-10-30 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	Conditional	-	Merchant-side user identifier. Required when checkFaceConsistency is omitted or N. When checkFaceConsistency=Y, provide exactly one of userId and faceContent. For the userId option, use an existing enrolled reference under the same merchant, for example from Connect enrollment. An arbitrary new userId cannot be used as a reference.The system will use this reference face for face consistency verification. When face consistency is not enabled, userId is still required and is used only as a user identifier.	"enrolled_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", "deeperMode": "STANDARD" }
checkFaceConsistency	String	1	false	N	Enables face consistency verification. Y: enabled; N: disabled. When Y, provide exactly one of userId and faceContent. This is a top-level field, alongside productConfig. The merchant must have this capability enabled.	"Y"
faceContent	FaceContent	-	Conditional	null	Merchant-provided reference image. Required when checkFaceConsistency=Y and userId is not supplied. Do not provide userId together with this object. See FaceContent below.	{"content":"BASE64_IMAGE_DATA","sourceOfFace2":"SELFIE"}

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"

deeperMode

String

false

CLOSED

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.

"CLOSED"

FaceContent

Field Name	Data Type	Max Length	Mandatory	Default Value	Description	Example Value
content	String	-	true	-	Standard Base64-encoded image data without a data URI prefix. Supports JPG/JPEG, PNG and BMP. The decoded reference image must not exceed 5 MB; the combined decoded reference and SDK Pano images must also not exceed 5 MB.	"BASE64_IMAGE_DATA"
rect	String	-	false	null	Optional face rectangle in pixels: left,top,width,height. Use comma-separated integers; left/top must be non-negative, width/height positive, and the rectangle must be within the uploaded image. If omitted, face detection is used. Do not pass left,top,right,bottom coordinates directly.	"100,80,200,200"
sourceOfFace2	String	-	false	SELFIE behavior	Reference source: SELFIE for a selfie/face photograph; the corresponding supported document docType for a document face; 00000001007 for a face from an otherwise unsupported document. Omitted or blank values are processed as SELFIE.	"SELFIE"

The faceContent object is flat: {content, rect, sourceOfFace2}; do not wrap it in face2. For a document image, set sourceOfFace2 to its docType; an optional rect must locate the face in that uploaded image.

When checkFaceConsistency=Y, supplying both or neither of userId and faceContent returns INVALID_ARGUMENT. If no enrolled reference is found for userId, initialization returns INVALID_ARGUMENT. Calling Connect/FaceCapture without creating an enrolled reference is insufficient.

checkFaceConsistency, userId and faceContent are top-level fields; deeperMode remains inside productConfig. With checkFaceConsistency omitted or N, userId is still required and faceContent alone does not enable verification. No sampling-rate parameter is accepted.

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`.
UNABLE_GET_IMAGE	F	The supplied faceContent image is empty, damaged or unsupported. Invalid Base64, oversized reference images and invalid rectangles return INVALID_ARGUMENT.

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", 
        "deeperMode": "STANDARD"
    }
}

Response Sample

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

Request Sample: Merchant-provided reference image

Use a new bizId and actual SDK metaInfo/Base64 image data. Do not supply userId. rect is optional.

copy
{
    "bizId": "VV2026101600000002",
    "metaInfo": "<SDK metaInfo>",
    "checkFaceConsistency": "Y",
    "faceContent": {
        "content": "BASE64_IMAGE_DATA",
        "sourceOfFace2": "SELFIE"
    },
    "productConfig": {
        "riskMode": "STANDARD",
        "deeperMode": "STANDARD"
    }
}