screen (New)

2025-10-17 02:58

Overview

API URL: /api/v3/aml/nss/screen

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

Request Parameters

Parameter	Data Type	Max Length	Description	Example
customerId	String	128	Required. Customer ID in merchant system.	"164248883****"
subjectType	String	8	Required. Verification subject type. Values: `PERSON`: Person `ENTITY`: Company
bizCode	String	64	Required. Business scenario code.	"MANUAL_SCAN_SANCTION"
person	Person	-	Required. Personal information. For details, please refer to Person. Note: Provide either the `person` or `entity` parameter. When `subjectType` is `PERSON`, you must provide the person parameter.	{ "personName": "Tom", "personCertNo": "46082119870811****" }
entity	Entity	-	Required. Company information. For details, please refer to Entity. Note: Provide either the `person` or `entity` parameter. When `subjectType` is `ENTITY`, you must provide the entity parameter.	-
extendData	Json	512	Optional. The data should contain all the fields that the user wants for screening.	{ “userId”: “12345”, “name”: “Jacky”, “dob”: “19770421”, “nationality”: “CN”, “idNo”: “123456xxx” }

Person

Parameter	Data Type	Max Length	Description	Example
personName	String	128	Required. English name	"Tom"
personLocalName	String	128	Optional. Local language. You set this value. Examples include Chinese and English.	"en"
personCertNo	String	128	Optional. ID number	"46082119870811****"
personGender	Enum	8	Optional. Gender	"Male"
personBirthday	String	16	Optional. Birthday	"1982/Jan/08"
personNationality	Enum	8	Optional. Nationality	-
personCountry	Enum	32	Optional. Country	"SG"

Entity

Parameter	Data Type	Max Length	Description	Example
entityName	String	256	Required. English name	-
entityLocalName	String	256	Optional. Local language. You set this value. Examples include Chinese and English.	"en"
entityCertNo	String	128	Optional. ID number	-
entityCountry	Enum	32	Optional. Country	"SG"

Response Parameters

Parameter	Data Type	Is return required?	Description	Example
eventId	String	Yes	The call ID generated by the AML system.	"6728d09e2113b33b6cc7e47a361c****"
decision	String	Yes	Specifies screening decisions `ACCEPT`: Did not hit any watchlist `REVIEW`: Potentially hit some watchlists	"REVIEW"
bizCode	String	Yes	Required. Business scenario code.	"MANUAL_SCAN_SANCTION"
hitResults	Object Array	Yes	Hit results. For details, see HitResult.	-
totalHits	Int	Yes	The number of total hits	1
rcrrRiskLevel	String	No	Specifies real-time CRR risk level `HIGH`: high risk `MEDIUM`: medium risk `LOW`: low risk	"LOW"
result	Result	Yes	The API request result, which contains information about the result of the API request, such as status and error codes.	{ "resultStatus": "S", "resultCode": "SUCCESS", "resultMessage": "Success" }

HitResult

Parameter	Data Type	Is return required?	Description	Example
scanArgs	String	Yes	Engine input parameters for the request scenario.	See Response Sample.
scanResult	String	Yes	Engine scan results for the request scenario.	"review"
hitReason	HitReason	No	Reason for the watchlist hit for the request.	{ "engineType": "SANCTION", "hitType": "name_match", "paramMatch": "John Doe", "recordMatch": "John Doe", "matchRate": 100, "matchStrategy": "s_person_name_common_src_full_name_similar" }
hitRecord	HitRecord	No	Watchlist records matched for the request.	See Response Sample.

HitReason

Parameter	Data Type	Is return required?	Description	Example
engineType	String	Yes	Type of engine matched: `SANCTION`: Sanctions watchlist engine. `PEP`: Politically exposed persons watchlist engine. `AM`: Adverse Media watchlist engine. `CUSTOM`: Customized watchlist engine.	"SANCTION"
hitType	String	Yes	Hit type: `name_match`: Name match hit. `id_match`: Document number match hit.	"name_match"
paramMatch	String	Yes	Hit input parameters	"John Doe"
recordMatch	String	Yes	Field values of the matched watchlist record	"John Doe"
matchRate	Int	Yes	Matching algorithm score	100
matchStrategy	String	Yes	Name of the matching algorithm	"s_person_name_common_src_full_name_similar"

HitRecord

Parameter	Data Type	Is return required?	Description	Example
id	String	Yes	AML system list ID	"584183"
version	String	Yes	AML system list version	1
originId	String	Yes	Source list record ID	"584183"
origin	String	Yes	Source list type, including `DOWJONES` and `WORLDCHECK`	"DOWJONES"
type	String	Yes	List record entity type `Person`: individual `Entity`: enterprise/organization	"Person"
action	String	Yes	Source list change type `add`: addition `del`: deletion `chg`: modification	"add"
activeStatus	String	Yes	Source list record status `Active`: active/valid `Inactive`: inactive/invalid	"Active"
date	String	Yes	Timestamp of the source list record’s change type.	"05-Aug-2025"
category	String	No	WorldCheck primary (level-1) category	"BANK"
subCategory	String	No	WorldCheck secondary (level-2) category	"PEP IO"
keywords	List<String>	No	WorldCheck-specific list grouping information	["AMCBA-TERR"]
profileNotes	String	No	Any other information in the source list associated with the person or entity.	-
gender	String	No	Gender, returned only when `type` is `Person`. `Male`: male `Female`: female `Unknown`: unknown gender	"Male"
deceased	String	Yes	Whether the person is deceased, returned only when `type` is `Person`. `Yes`: deceased `No`: alive	"No"
position	String	No	The WorldCheck list describes the social and political status of individuals or organizations.	"Member of Legislature"
age	String	No	Person age. Available only when `type` is `Person`.	"32"
ageDate	String	No	Age last updated time. Available only when `type` is `Person`.	"05-Aug-2025"
groups	List<String>	Yes	List group in the AML system.	[ "DEMO_PERSON_SANCTION" ]
nameDetails	List<Name>	Yes	Name details list from the source list record. This parameter records name information across multiple dimensions.	[ { "nameType": "Primary Name", "nameValueList": [ { "firstName": "John", "surname": "Doe" } ] } ]
descriptions	List<Description>	Yes	Source list structure description. `description1`: First-level group in the source list record. `description2`: Second-level group in the source list record. `description3`: Third-level group in the source list record.	[ { "description1": "3", "description2": "1" } ]
dateDetails	List<Date>	No	Date details for the source list record.	[ { "dateType": "Date of Birth", "dateValueList": [ { "day": "10", "month": "May", "year": "1966" } ] } ]
sanctionsReferences	List<Reference>	No	Sanctions source reference information.	[ { "toDay": "10", "toMonth": "Sep", "toYear": "2019", "value": "Sanctioned for financial crimes" } ]
countryDetails	List<Country>	Yes	Country information details.	[ { "countryType": "Citizenship", "countryValueList": [ { "code": "example_country_code" } ] } ]
idNumberTypes	List<ID>	No	ID information for the `Person` or `Entity`.	[ { "idType": "Company Identification No.", "idValueList": [ { "value": "914403001922038216" } ] } ]
sourceDescription	List<Source>	No	Information source list for the `Person` or `Entity`. The `name` field indicates the source for the individual, organization, or related party.	{ "Source": [ { "name": "http://www.news**.com.pk/NewsDec2002/newsbeatdec2.htm" }, { "name": "http://www.newsline**.com/2002/12/the-prime-of-mr-jamali/" } ] }
addressList	List<Address>	No	Address information list.	[ { "addressCountry": "kp" } ]
roleDetail	List<Roles>	No	Position or occupation details list.	参考返回示例
birthPlace	List<Place>	No	Place of birth information list. The `name` field indicates the place of birth.	[ { "name": "Wonsan,North Korea" } ]
images	List<Image>	No	Person image link list. The `url` field indicates the image URL.	[ { "url": "https://img.huffingtonpost.com/asset/5add68**.jpeg?ops=scalefit_630_noupscale" } ]
companyDetailsList	List<CompanyDetails>	No	Address value element for the referenced agency in the sanctions or official list.	{ "AddressLine": "75 Danbury Road, Unit B5, Copps Hill Court", "AddressCity": "Ridgefield;Connecticut;06877", "AddressCountry": "USA" }
vesselDetailsList	List<VesselDetails>	No	Vessel entity detail value list.	[ { "VesselCallSign": "3E5918", "VesselType": "LNG Carrier", "VesselFlag": "PANA" }, { "VesselFlag": "NOTK" } ]

Name

Parameter

Data Type

Is return required?

Description

Example

nameType

String

Yes

Name type for the source list record.

"Primary Name"

nameValueList

List<NameValue>

Yes

Name value for the source list record.

[

{

"firstName": "John",

"surname": "Doe"

}

]

NameValue

Parameter	Data Type	Is return required?	Description	Example
TitleHonorific	String	No	Honorific	"Lord"
FirstName	String	No	Given name	"**"
MiddleName	String	No	Middle name	-
Surname	String	No	Family name	"Doe"
MaidenName	String	No	Maiden name	-
Suffix	String	No	Suffix	"Junior"
EntityName	String	No	Company name	"** Technologies Co., Ltd."
SingleStringName	String	No	Normalized full name	-
OriginalScriptName	String	No	Full name in local non-Latin script	-

Date

Parameter

Data Type

Is return required?

Description

Example

dateType

String

Yes

Date type.

"Date of Birth"

dateValueList

List<DateValue>

Yes

Date detail value. The dnotes field provides extra information about the date.

[

{

"day": "10",

"month": "May",

"year": "1966"

}

]

Reference

Parameter	Data Type	Is return required?	Description	Example
sinceDay	String	No	Sanctions source reference start day	"03"
sinceMonth	String	No	Sanctions source reference start month	"Jun"
sinceYear	String	No	Sanctions source reference start year	"2021"
toDay	String	No	Sanctions source reference end day	"10"
toMonth	String	No	Sanctions source reference end month	"Sep"
toYear	String	No	Sanctions source reference end year	"2019"
value	String	No	Sanctions source reference key value	"Sanctioned for financial crimes"
name	String	No	Sanctions source reference name	-

Country

Parameter

Data Type

Is return required?

Description

Example

countryType

String

Yes

Country information type.

"Country of Registratio"

countryValueList

List<CountryValue>

Yes

Country detail value. The code field indicates the country code.

[

{

"code": "cn"

}

]

ID

Parameter

Data Type

Is return required?

Description

Example

idType

String

Yes

ID type

"Company Identification No."

idValueList

List<IDValue>

Yes

ID detail value

[

{

"value": "914403001922038216"

}

]

IDValue

Parameter	Data Type	Is return required?	Description	Example
value	String	Yes	ID value	"914403001922038216"
idNotes	String	No	Additional information about the ID value.	-

Address

Parameter	Data Type	Is return required?	Description	Example
addressLine	String	No	Address details	"12 Throsby Street"
addressCity	String	No	City	"Spearwood;Western Australia;6163"
addressCountry	String	No	Country	"AUSTR"
addressState	String	No	Continent	-
url	String	No	URL	-

Role

Parameter

Data Type

Is return required?

Description

Example

roleType

String

Yes

Position type.

"Primary Occupation"

occTitleList

List<OccTitle>

Yes

Position title details.

[

{

"occCat": "4",

"sinceDay": "05",

"sinceMonth": "Oct",

"sinceYear": "2021",

"toDay": "11",

"toMonth": "Jan",

"toYear": "2023",

"value": "Secretary General, Ministry of Finance"

}

]

OccTitle

Parameter	Data Type	Is return required?	Description	Example
sinceDay	String	No	Start day	"05"
sinceMonth	String	No	Start month	"Oct"
sinceYear	String	No	Start year	"2021"
toDay	String	No	End day	"11"
toMonth	String	No	End month	"Jan"
toYear	String	No	End year	"2023"
occCat	String	No	Position code	"4"
value	String	No	Position	"Secretary General, Ministry of Finance"

CompanyDetails

Parameter	Data Type	Is return required?	Description	Example
addressLine	String	No	Address details	"12 Throsby Street"
addressCity	String	No	City	"Spearwood;Western Australia;6163"
addressCountry	String	No	Country	"AUSTR"
url	String	No	URL	-

VesselDetails

Parameter	Data Type	Is return required?	Description	Example
vesselCallSign	String	No	Vessel call sign value	"3E5918"
vesselType	String	No	Vessel type	"LNG Carrier"
vesselTonnage	String	No	Vessel tonnage	-
vesselGRT	String	No	Vessel gross tonnage	-
vesselOwner	String	No	Vessel owner name	-
vesselFlag	String	No	Dow Jones region code identifier for the vessel entity	"PANA"

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 codes appear in API common result codes. See that list for details.

Samples

Request Sample

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

copy
{
  "bizCode":"ONBOARDING_PERSON_DEFAULT",
  "customerId":"164248883****",
  "person":{
    "personName":"Tom",
    "personCertNo":"820108-123456"
  },
  "subjectType":"PERSON"
}

Response Sample

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

NOT HIT

copy
{
    "decision": "ACCEPT", 
    "bizCode": "ONBOARDING_PERSON_DEFAULT", 
    "hitResults": [ ], 
    "totalHits": 0, 
    "rcrrRiskLevel": "", 
    "eventId": "6728d09e2113b33b6cc7e47a361c****", 
    "result": {
        "resultCode": "SUCCESS", 
        "resultMsg": "success", 
        "resultStatus": "S"
    }
}

copy
{
    "decision": "REVIEW", 
    "bizCode": "ONBOARDING_PERSON_DEFAULT", 
    "hitResults": [
        {
            "scanArgs": "[{\"disableSearch\":false,\"groupName\":\"GROUP1\",\"requestArgMap\":{\"BIRTHDAY\":\"19660510\",\"CITIZENSHIP\":\"\",\"PERSON_NAME\":\"John Doe\",\"ID\":\"\",\"GENDER\":\"\"},\"watchlistGroups\":[\"DEMO_PERSON_SANCTION\"]}]", 
            "scanResult": "review", 
            "hitReason": {
                "engineType": "SANCTION", 
                "hitType": "name_match", 
                "paramMatch": "John Doe", 
                "recordMatch": "John Doe", 
                "matchRate": 100, 
                "matchStrategy": "s_person_name_common_src_full_name_similar"
            }, 
            "hitRecord": {
                "id": "example_12345", 
                "origin": "DOWJONES", 
                "type": "Person", 
                "activeStatus": "Active", 
                "nameDetails": [
                    {
                        "nameType": "Primary Name", 
                        "nameValueList": [
                            {
                                "firstName": "John", 
                                "surname": "Doe"
                            }
                        ]
                    }
                ], 
                "descriptions": [
                    {
                        "description1": "3", 
                        "description2": "1"
                    }
                ], 
                "dateDetails": [
                    {
                        "dateType": "Date of Birth", 
                        "dateValueList": [
                            {
                                "day": "10", 
                                "month": "May", 
                                "year": "1966"
                            }
                        ]
                    }
                ], 
                "sanctionsReferences": [
                    {
                        "toDay": "10", 
                        "toMonth": "Sep", 
                        "toYear": "2019", 
                        "value": "Sanctioned for financial crimes"
                    }
                ], 
                "countryDetails": [
                    {
                        "countryType": "Citizenship", 
                        "countryValueList": [
                            {
                                "code": "example_country_code"
                            }
                        ]
                    }
                ]
            }
        }
    ], 
    "totalHits": 1, 
    "rcrrRiskLevel": "", 
    "eventId": "6728d09e2113b33b6cc7e47a361c****", 
    "result": {
        "resultCode": "SUCCESS", 
        "resultMsg": "success", 
        "resultStatus": "S"
    }
}