ZOLOZZOLOZDOCS

screen

Overview 

API Name: AML Watch Screening API

API URL: /api/v1/aml/analyze

API Description: Provides screening capabilities with a user-defined watchlist.

Structure

Request Parameters 

Parameter 

Data Type

Max Length

Description

Example

requestID

String

32B

Required. Unique business ID for tracing purposes.

aa3b8bab7a9340f2b3021645816b0964

bizCode

String

64B

Required. Business scenario code. 

ONBOARDING

tenantID

String

8B

Required. Customer's unique ID.

HKGYSC

extendData

Json

1MB

Required. The data should contain all the fields that the user wants for screening. 

{

“userId”: “12345”,

“name”: “Jacky”,

“dob”: “19770421”,

“nationality”: “CN”,

“idNo”: “123456xxx”

}

Response Parameters

Parameter

Data Type 

Max Length

Description

Example

requestID

String

32B

Unique business ID for tracing purposes

aa3b8bab7a9340f2b3021645816b0964

decision

String

64B

Screening decisions: 

ACCEPT: Did not hit any watchlist

REJECT: Hit some watchlists

REVIEW: Potentially hit some watchlists

ACCEPT

REJECT

REVIEW

hitResults

Object Array

3MB

Hit details

result.resultCode

String

64B

Reason for the screening decision. See more details in API-specific result codes. 

AML_CLEAN

result.resultStatus

String

32B

Result status. Possible values and their meanings are as below: 

"S": successful

"F": failed

"U": unknown issue

S

result.resultMessage

String

1KB

Result message.

See more details in API-specific result codes.

No hit found.

Result

Result Process Logic

For different request results, the following different actions will be performed. See the following for details:

  • If the value of the result.resultStatus is S, the screening API has been invoked successfully.
  • If the value of the result.resultStatus is F, the invocation of the screening API has failed. Check the error codes and messages for more information about the possible reasons why.

Common error codes

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

API-specific result codes

The following table shows the possible result codes specific to this screening API:

resultCode

resultMessage

resultStatus

Max Length

Description

AML_CLEAN

No hit found.

S

32B

Not hit found

AML_REJECT

One or more hits are found.

S

32BNot hit found

SCENARIO_ROUTE_FAILED

Failed to find existing scenarios matching the current request.

F

32BNot hit found

AML_ERR_SIFT_WRONGPARAMETER

Input parameters are invalid. 

F

32BNot hit found

AML_ERR_SIFT_AMLSYSERROR

System error.

U

32BNot hit found

Samples

Request Sample

The following sample shows what a request sent by the merchant server would look like:

copy
{
"bizCode": "MANUAL_SCAN_SANCTION",
"extendData": {
"certName": "Peter"
},
"tenantID": "XXX",
"tntInstID": "XXX"
}

To find out the details of XXX in "XXX", such as in "tenantID": "XXX" and "tntInstID": "XXX", please contact ZOLOZ BD/Solution team.

Response Sample

The following sample shows what a response returned by the AML server returns would look like:

  • NOT HIT
copy
{
  "result": {
    "resultStatus": "S",
    "resultCode": "AML_CLEAN",
    "resultMessage": "Success"
  },
  "hitResults":"",
  "requestID":"2112121234141151", 
  "decision": "ACCEPT"   
}
  • HIT
copy
{
  "decision":"REJECT",
  "hitResults":[
    {
      "reason":"{"date":"07-Oct-2021","engineType":"WISE_NEXT_SANCTION","hitId":"xxx","hitType":1,"matchRate":98,"origin":"DOWJONES","paramMatch":"xxx","record":{"action":"add","activeStatus":"Active","addressList":[],"birthPlace":[{"name":"Russia"}],"countryDetails":[{"countryType":"Citizenship","countryValueList":[{"code":"ru"}]},{"countryType":"Resident of","countryValueList":[{"code":"NOTK"}]}],"date":"07-Oct-2021","dateDetails":[{"dateType":"Date of Birth","dateValueList":[{"day":"xx","month":"Mar","year":"1975"}]}],"deceased":"No","gender":"Male","groups":["ALL_SANCTION_LIST"],"id":"12611176","nameDetails":[{"nameType":"Primary Name","nameValueList":[{"firstName":"xx","middleName":"xx","originalScriptNameList":["xx"],"surname":"xx"}]},{"nameType":"Spelling Variation","nameValueList":[{"firstName":"xx","middleName":"xx","surname":"xx"},{"firstName":"xx","middleName":"xx","surname":"xx"}]}],"origin":"DOWJONES","originId":"xx","sanctionsReferences":[{"sinceDay":"06","sinceMonth":"Oct","sinceYear":"2021","value":"1770"}],"type":"Person","version":1},"recordBirthDays":[],"recordMatch":"xx","recordNations":[],"recordResCountries":[],"tag":"GROUP1.PERSON_NAME","type":"Individual"}",
      "scanArgs":"[{\"groupName\":\"GROUP1\",\"requestArgMap\":{\"PERSON_NAME\":\"xx xx\",\"GENDER\":\"\"},\"watchlistGroups\":[\"ALL_SANCTION_LIST\"]},{\"groupName\":\"GROUP2\",\"requestArgMap\":{},\"watchlistGroups\":[]},{\"groupName\":\"GROUP3\",\"requestArgMap\":{},\"watchlistGroups\":[]},{\"groupName\":\"GROUP4\",\"requestArgMap\":{},\"watchlistGroups\":[]}]",
    },
    {
      "reason":"{"date":"24-May-2018","engineType":"WISE_NEXT_PEP_AM","hitId":"xxx","hitType":1,"matchRate":97,"origin":"DOWJONES","paramMatch":"xx","record":{"action":"add","activeStatus":"Inactive","addressList":[{"addressCountry":"ve"}],"countryDetails":[{"countryType":"Citizenship","countryValueList":[{"code":"ve"}]},{"countryType":"Resident of","countryValueList":[{"code":"ve"}]},{"countryType":"Jurisdiction","countryValueList":[{"code":"ve"}]}],"date":"24-May-2018","dateDetails":[{"dateType":"Inactive as of (PEP)","dateValueList":[{"day":"24","month":"May","year":"2018"}]}],"deceased":"No","descriptions":[{"description1":"1"}],"gender":"Male","groups":["ALL_PEP "],"id":"xxx","nameDetails":[{"nameType":"Primary Name","nameValueList":[{"firstName":"xx","middleName":"O.","surname":"xx P."}]},{"nameType":"Also Known As","nameValueList":[{"firstName":"xx","middleName":"O.","surname":"xx"},{"firstName":"xx","middleName":"O.","surname":"P."},{"firstName":"xx O.","surname":"xx P."}]},{"nameType":"Spelling Variation","nameValueList":[{"firstName":"xx","middleName":"O.","surname":"xx P."},{"firstName":"xx O.","surname":"xx P."}]}],"origin":"DOWJONES","originId":"3359609","roleDetail":[{"occTitleList":[{"occCat":"4","value":"See Previous Roles"}],"roleType":"Primary Occupation"},{"occTitleList":[{"occCat":"4","sinceDay":"08","sinceMonth":"Sep","sinceYear":"2014","value":"xxx"}],"roleType":"Previous Roles"}],"type":"Person","version":1},"recordBirthDays":[],"recordMatch":"xx P., xx O.","recordNations":[],"recordResCountries":[],"tag":"GROUP1.PERSON_NAME","type":"Individual"}",
    "scanArgs":"[{\"groupName\":\"GROUP1\",\"requestArgMap\":{\"PERSON_NAME\":\"zz xx\",\"GENDER\":\"\"},\"watchlistGroups\":[\"ALL_PEP\"]},{\"groupName\":\"GROUP2\",\"requestArgMap\":{},\"watchlistGroups\":[]},{\"groupName\":\"GROUP3\",\"requestArgMap\":{},\"watchlistGroups\":[]},{\"groupName\":\"GROUP4\",\"requestArgMap\":{},\"watchlistGroups\":[]}]",
    }
  ],
    "requestID":"39c4450e94353003a67d0d30994d7d6c",
    "result":{
    "resultCode":"AML_REJECT",
    "resultMessage":"One or more hits are found.",
    "resultStatus":"S"
    }
    }