AML Watch Screening
API Integration
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 | 32B | Not hit found |
SCENARIO_ROUTE_FAILED | Failed to find existing scenarios matching the current request. | F | 32B | Not hit found |
AML_ERR_SIFT_WRONGPARAMETER | Input parameters are invalid. | F | 32B | Not hit found |
AML_ERR_SIFT_AMLSYSERROR | System error. | U | 32B | Not hit found |
Samples
Request Sample
The following sample shows what a request sent by the merchant server would look like:
{
"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
{
"result": {
"resultStatus": "S",
"resultCode": "AML_CLEAN",
"resultMessage": "Success"
},
"hitResults":"",
"requestID":"2112121234141151",
"decision": "ACCEPT"
}
- HIT
{
"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"
}
}