initialize

2026-04-02 07:03

Overview

API URL: /api/v1/zoloz/location/initialize
API Description: This API initializes the location detection process.

Note:
Before calling the GeoTrust Locator API, ensure that the client has integrated the SDK for location detection functionality. For details, see App SDK-mode integration.
This API does not support repeated calls and is therefore not idempotent.

Request Parameter

Field Name	Data Type	Max Length	Mandatory	Fault Value	Description	Sample
bizId	String	32	Y	-	Business ID, the unique identifier of a business transaction, used for business tracking. For example, a serial number from the merchant's business-related database. Note: The ZOLOZ server does not verify the uniqueness of this field. To facilitate easier business tracking, it is recommended that merchants generate the Business ID on their server side and ensure its uniqueness.	"2017839040588699"
metaInfo	String	512	Y	-	Meta information from the SDK and user's device. The value of this field is returned by the ZOLOZ SDK in JSON string format. Note: Do not modify the returned value — pass it through as-is. For H5 integration mode, set this field to `MOB_H5`.	{ "deviceType": "android", "appVersion": "1.0.9", "osVersion": "9", "appName": "com.zoloz.atomic.client", "bioMetaInfo": "3.46.0:2916352,0", "apdidToken": "69b74bfe-bf7f-4d3b-ac59-907ee09e****", "deviceModel": "MI 6", "zimVer": "1.0.0" }
userId	String	64	Y	-	A user ID provided by the merchant, or any other value that can be used to identify a specific user, such as a phone number or email address. It is recommended to pre-process the `userId` field for data desensitization, for example by applying a hashing algorithm.	"123456abcd"
detectMock	Boolean	-	N	true	Whether to enable simulated location detection. If enabled, the system will detect whether the user is using fake GPS or location spoofing software. Valid values: `true`: Enable detection `false`: Disable detection	true
detectVpn	Boolean	-	N	true	Whether to enable VPN connection detection. If enabled, the system will detect whether the user is connecting through a VPN. Valid values: `true`: Enable detection `false`: Disable detection	true
geoFenceMatch	List	-	N	-	A geofencing match list used to verify whether the user’s actual location falls within specified administrative regions. Supports one or more region codes. Currently only the following are supported: `HK`: Hong Kong, China `MO`: Macao, China If this field is not provided or an empty array is passed, geofencing detection will be disabled.	["HK", "MO"]

Response Parameter

Field Name	Data Type	Mandatory	Description	Sample
result	Result	Y	The result of the API request, including the operation status, result code, and message.	{ "resultStatus": "S", "resultCode": "SUCCESS", "resultMessage": "Success" }
transactionId	String	N	The unique transaction ID generated by the ZOLOZ server for the location detection process. This ID must be used as an input parameter when calling the GeoTrust Locator `checkresult` API. Note: The `transactionId` is only returned after the transaction has entered the processing stage. If an error occurs before processing begins, the system will not generate or return a `transactionId`. This includes, but is not limited to, the following scenarios: Invalid request parameters (e.g., incorrect format or missing mandatory fields). Request failed to reach the server (e.g., network issues or gateway failure). Request rejected due to system rate limiting.	"G000000005FID2020030400000000000157****"
clientCfg	String	N	Client-side configuration data. The SDK will use this configuration to perform subsequent operations. This field must be passed unchanged to the client SDK. Note: It is only returned when `result.resultStatus` is `S`.	"{...}"

Result

Perform the next action based on the request result, as follows:

When the value of result.resultStatus is S, it indicates that the call to the ZOLOZ GeoTrust Locator initialize API was successful, and a unique transaction ID has been returned.
When the value of result.resultStatus is F, it indicates that the call to the ZOLOZ GeoTrust Locator initialize API failed. Please check the error code for more information about the error, and analyze the cause of the failure.

API-common Result codes

For the full list of common result codes, see the API common result code.

API-specific Result codes

The result codes for the GeoTrust Locator initialize API are listed in the table below.

resultCode	resultStatus	Description
SUCCESS	S	API call succeeded.
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.
INVALID_ARGUMENT	F	Invalid input parameters. For details, refer to the `resultMessage` field in the response.
SYSTEM_ERROR	F	An internal error occurred. For details, refer to the `resultMessage` field in the response.
METAINFO_NOT_SUPPORT	F	The client version does not support location detection. The 57th bit in `metaInfo` is less than 1.
INVALID_PARAM	F	Request parameter error.
UNKNOWN	F	Uncategorized system error.
CONFIG_EMPTY	F	Location configuration is empty.

Sample

Request Sample

copy
{
    "bizId": "2017839040588699", 
    "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-907ee09e****\",\"deviceModel\":\"MI 6\",\"zimVer\":\"1.0.0\"}", 
    "userId": "user_123456", 
    "detectMock": true, 
    "detectVpn": true, 
    "geoFenceMatch": [
        "HK", 
        "MO"
    ]
}

Response Sample

copy
{
    "result": {
        "resultStatus": "S", 
        "resultCode": "SUCCESS", 
        "resultMessage": "Success"
    }, 
    "transactionId": "G000000005FID2020030400000000000157****", 
    "clientCfg": "{\"protocol\":{\"timestamp\":\"1634567890123\",\"signature\":\"xxxxx\"}}"
}