Smile - Verify Initialize API

2026-08-11 08:14

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/smile/verify/initialize
API Description: Used to initialize the verification process for user biometric features.

Request Parameters

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: ZOLOZ does not validate the uniqueness of this value; the merchant side must ensure the uniqueness of the business ID.	"2017839040588699"
metaInfo	String	512	Yes	-	Metadata of the SDK and user device. The value is returned by the ZOLOZ SDK in JSON string format.	{ \"deviceType\": \"android\", \"appVersion\": \"1.0.9\", \"osVersion\": \"9\", \"appName\": \"com.zoloz.atomic.client\", \"bioMetaInfo\": \"3.46.0:2916352,0\", \"apdidToken\": \"69b74bfe-bf7f-4d3b-ac59-907ee09e7955\", \"deviceModel\": \"MI 6\", \"zimVer\": \"1.0.0\" }
verificationType	String	32	No	face	Biometric verification type. Supported values: `palm`: Palm recognition `face`: Face recognition	"palm"
multiMatchControl	String	32	No	SECONDARY_VERIFY	Multi-face matching control strategy. This parameter takes effect only when `verificationType` is set to `face`. Supported values: `SECONDARY_VERIFY`: When multiple faces are detected, the system triggers secondary verification. `AUTO_PASS`: When multiple faces are detected, the system automatically passes the verification and selects the user with the highest matching score. `AUTO_FAIL`: When multiple faces are detected, the system automatically fails the verification and returns a list of similar faces.	"SECONDARY_VERIFY"

Response Parameters

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" }
clientCfg	String	No	The Client configuration information, including parameters about the SDK connection and behavior. Note: The value of this field is returned only when the `result.resultStatus` field is `S`.	"{\"clientStartIndex\":1, \"factorContext\":{...}}"
transactionId	String	No	The unique transaction ID generated for this verification. 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.	"G000000001FSE2025052300000001218988****"

Result

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 Smile Verify Initialize API.

resultCode	resultStatus	Description
SUCCESS	S	The API call is successful.
INVALID_ARGUMENT	F	Input parameters are invalid. For more information about which parameter is invalid, check the returned `resultMessage`.
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.
SYSTEM_ERROR	F	Internal system error. For error details, check the returned `resultMessage`.

Sample

Request Sample

copy
{
    "bizId": "2017839040588699", 
    "verificationType": "palm", 
    "metaInfo": "{
         \"deviceType\": \"android\",
         \"appVersion\": \"1.0.9\",
         \"osVersion\": \"9\",
          \"appName\": \"com.zoloz.atomic.client\",
         \"bioMetaInfo\": \"3.46.0:2916352,0\",
         \"apdidToken\": \"69b74bfe-bf7f-4d3b-ac59-907ee09e7955\",
         \"deviceModel\": \"MI 6\",
         \"zimVer\": \"1.0.0\"
   }"
}

Response Sample

copy
{
    "result": {
        "resultStatus": "S", 
        "resultCode": "SUCCESS", 
        "resultMessage": "Success"
    }, 
    "clientCfg": "{\"clientStartIndex\":1, \"factorContext\":{...}}", 
    "transactionId": "G000000001FSE2025052300000001218988****"
}