AML Watch Screening

2023-04-21 07:41

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:

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"   
}

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"
    }
    }