All Products
Search

This Product

    Financial Intelligence Engine:Interact with the ZOLOZ gateway

    Document Center

    Financial Intelligence Engine:Interact with the ZOLOZ gateway

    Last Updated:Jun 26, 2026

    ZOLOZ APIs are language-independent and exposed by a gateway service. Before you integrate ZOLOZ APIs, make sure that you can communicate with the ZOLOZ gateway service.

    Before you begin

    About the task

    You can interact with the gateway service by integrating libraries that implement the gateway protocol, or by implementing the protocol yourself.

    ZOLOZ provides the following libraries:

    • Java Library: use this library if your programming language is Java

    This topic describes how to integrate ZOLOZ APIs by using the Java library. 

    About the authentication test API

    This topic uses the authentication test API for demonstration. The authentication test API is not associated with any specific ZOLOZ product. It is designed for authentication testing only. It accepts any valid JSON object and returns the same JSON object, similar to the echo command.

    Like other APIs, the authentication test API is built on the gateway service. After you successfully call the authentication test API, you can integrate other APIs in the same way. 

    Steps

    Integrate ZOLOZ APIs using libraries 

    Use the Java library

    The ZOLOZ Java library is published on the Maven central repository. 

    Perform the following steps to use the Java library to interact with the gateway service and call an API.

    1. Introduce the library into your Maven project by adding the following dependencies to the POM file.

    <dependency> <groupId>com.zoloz.api.sdk</groupId> <artifactId>zoloz-api-sdk</artifactId> <version>1.0.2</version> </dependency>

    <dependency>
 <groupId>com.zoloz.api.sdk</groupId>
 <artifactId>zoloz-api-sdk</artifactId>
 <version>1.0.2</version>
</dependency>

    For the latest dependency versions, see pom.xml.

    1. Import the OpenApiClient class

    import com.zoloz.api.sdk.client.OpenApiClient;

    1. Instantiate an OpenApiClient instance and configure the instance with the API credentials, as well as the Client ID, the ZOLOZ transaction public key, and the encoded merchant transaction private key.

    //Set proper values to following vairables
String clientId = "<Client ID>";
String zolozPublicKey = "<ZOLOZ's public key content encoded in base64>";
String merchantPrivateKey = "<The merchant's private key content encoded in base64>";

//Instantiate an OpenApiClient object with signature validation and encryption both enabled by default
OpenApiClient client = new OpenApiClient(); 
client.setHostUrl("<ZOLOZ gateway URL>");
client.setClientId(clientId);
client.setMerchantPrivateKey(merchantPrivateKey);
client.setOpenApiPublicKey(zolozPublicKey);
//NOTE: uncomment the following line if you want to skip signature validation for response
//client.setSigned(false); 
//NOTE: uncomment the following line if you want to disable encryption
//client.setEncrypted(false);

    For the ZOLOZ gateway URL, please refer to Understand service endpoints.

    1. Call the API

    //Set the name of authentication test API 
String apiName = "v1.aml.analyze";

//Set the request, a simple JSON object
String request = "{\"bizCode\":\"TEST\",\"extendData\":{\"certName\":\"test\",\"gender\":\"male\",\"nationality\":\"u\"},\"tenantID\":\"TEST\",\"tntInstID\":\"GLOBAL\"}";

//Call the API, the response is expected to be a JSON string of the same JSON object
String response = client.callOpenApi(apiName, request);

    1. Receive a response from the API

    {
 /**details for the hit**/
 "hitResults":[
 {
 "reason":"{
 "date":"2021/04/01",
 /**screening engine type**/
 "engineType":"WISE_NEXT_SANCTION",
 /** if is Financially Exposed Person */
 "fep":-1,
 /**ID for hit watchlist**/
 "hitId":"FAWC51068",
 /**Hit type; this field is optional, use the tag field below instead**/
 "hitType":1,
 /**screening matching score**/
 "matchRate":100,
 /**watchlist provider**/
 "origin":"DOWJONES",
 /**Engine scan group**/
 "originCategory":"US",
 /**Input parameters**/
 "paramMatch":"carrie lam",
 /** Whether the person is a politically exposed person (PEP) */
 "pep":1,
 
 /**Matched list details**/
 "record":{
 /**Address information**/
 "addressList":[
 {
 "addressCity":"",
 "addressCountry":"hk",
 "addressLine":"The Peak",
 "addressState":""
 }
 ],
 /**Place of birth**/
 "birthPlace":[
 {
 "name":"Hong Kong"
 }
 ],
 /**List category**/
 "category":"POLITICAL INDIVIDUAL",
 /**Nationality information**/
 "countryDetails":[
 {
 "countryType":"Resident of",
 "countryValueList":[
 {
 "code":"hk"
 }
 ]
 },
 {
 "countryType":"Citizenship",
 "countryValueList":[
 {
 "code":"hk"
 }
 ]
 }
 ],
 "date":"2021/04/01",
 /**Date of birth**/
 "dateDetails":[
 {
 "dateType":"Date of Birth",
 "dateValueList":[
 {
 "day":"13",
 "month":"May",
 "year":"1957"
 }
 ]
 }
 ],
 /**Whether it is deprecated**/
 "deceased":"No",
 "gender":"Female",
 /**List group**/
 "groups":[
 "TEST"
 ],
 /**List ID**/
 "id":"WC51068",
 /**List ID document information**/
 "idNumberTypes":[
 {
 "idType":"Passport No.",
 "idValueList":[
 {
 "idNotes":"HONG KONG",
 "value":"test"
 }
 ]
 }
 ],
 "keywords":[
 "OFAC-HK-EO13936",
 "OFAC"
 ],
 /**Alias**/
 "nameDetails":[
 {
 "nameType":"Primary Name",
 "nameValueList":[
 {
 "firstName":"test",
 "surname":"test",
 "titleHonorific":""
 }
 ]
 },
 {
 "nameType":"Also Known As",
 "nameValueList":[
 {
 "firstName":"Yuet Ngor",
 "surname":"CHENG"
 }
 ]
 },
 {
 "nameType":"Native Character Name",
 "nameValueList":[
 {
 "language":"zh-CN",
 "originalScriptNameList":[
 "\xE6\x9E\x97\xE9\x83\x91\xE6\x9C\x88\xE5\xA8\xA5"
 ]
 }
 ]
 }
 ],
 "origin":"WORLDCHECK",
 "originId":"51068",
 /**Position**/
 "position":"Chief Executive of the Hong Kong Special Administrative Region",
 /**Subcategory**/
 "subCategory":"PEP N",
 "type":"Person"
 },
 "recordBirthDays":[
 "19570513"
 ],
 "recordBirthPlace":"Hong Kong",
 /**List ID document number**/
 "recordIdentifyNo":"TEST",
 /**Match records**/
 "recordMatch":"LAM",
 "recordNations":[
 "hk"
 ],
 "recordResCountries":[
 "hk"
 ],
 /**Engine tag information**/
 "tag":"GROUP1.PERSON_NAME",
 /**List type. Individual: individual,Company: company, Vessel:, Other: other **/
 "type":"Individual"
 }",
 /**Engine scan parameters**/
 "scanArgs":"[{\"groupName\":\"GROUP1\",\"requestArgMap\":{\"PERSON_NAME\":\"Li Yi\"},\"watchlistGroups\":[\"ALL_SANCTION_WATCHLIST\"]}]",
 "scanTarget":"NOT_USED",
 /**Engine scan conclusion**/
 "scanResult":"review"
 }
 ],
 "requestID":"2112121234141151",
 "amlDecision":"ACCEPT",
 "amlResultCode":"AML_CLEAN"
}

    Resources

    JAR and Scripts

    The libraries are open-source on GitHub. You can find the source code at: