扫描信息接口（新版）

2025-10-17 02:55

概览

API URL：/api/v3/aml/nss/screen
API 描述：该接口用于提供名单筛查扫描的结果。客户提供扫描入参后，根据不同的扫描场景和扫描逻辑，可以得到包括政治高风险人物、制裁名单、负面新闻等名单扫描的结果。

请求参数

字段名称	数据类型	最大长度	是否必填	默认值	描述	示例值
customerId	String	128	是	-	商户系统内部的客户ID。	"164248883****"
subjectType	String	8	是	-	验证对象类型，取值： `PERSON`：个人 `ENTITY`：企业	"PERSON"
bizCode	String	64	是	-	业务场景码，可在ZOLOZ Portal中获取。	"ONBOARDING_PERSON_DEFAULT"
person	Person	-	是	-	个人信息，参数定义详见Person。说明：`person`和`entity`需传入其中一个。当`subjectType`为`PERSON`时，必须传入该参数。	{ "personName": "Tom", "personCertNo": "820108-123456" }
entity	Entity	-	是	-	企业信息，参数定义详见Entity。说明：`person`和`entity`需传入其中一个。当`subjectType`为`ENTITY`时，必须传入该参数。	-
extendData	String	512	否	null	扩展数据，格式为JSON字符串。	-

Person字段说明

字段名称	数据类型	最大长度	是否必填	默认值	描述	示例值
personName	String	128	是	-	个人的英文名字	"Tom"
personLocalName	String	128	否	null	本地语言，由客户自定义设置，包括但不限于中文、英语等。	"en"
personCertNo	String	128	否	null	个人证件号	"820108-123456"
personGender	Enum	8	否	null	性别	"Male"
personBirthday	String	16	否	null	出生日期	"1982/Jan/08"
personNationality	Enum	8	否	null	国籍	-
personCountry	Enum	32	否	null	国家	"SG"

Entity字段说明

字段名称	数据类型	最大长度	是否必填	默认值	描述	示例值
entityName	String	256	是	-	企业的英文名称	-
entityLocalName	String	256	否	null	本地语言，由客户自定义设置，包括但不限于中文、英语等。	"en"
entityCertNo	String	128	否	null	企业证件号	-
entityCountry	Enum	32	否	null	国家	"SG"

返回参数

字段名称	数据类型	必须返回	描述	示例值
eventId	String	是	AML系统生成的本次调用ID。	"6728d09e2113b33b6cc7e47a361c****"
decision	String	是	是否命中监控名单记录。 `ACCEPT`：未命中任何监控名单记录。 `REVIEW`：命中了监控名单记录。	"REVIEW"
bizCode	String	是	返回的业务场景码。	"ONBOARDING_PERSON_DEFAULT"
hitResults	HitResult	是	命中的名单记录的结果，参数定义详见HitResult。	参考返回示例
totalHits	Int	是	命中的名单记录的数量。	1
rcrrRiskLevel	String	否	实时客户风险等级，如果未配置将返回空字符串。 `HIGH`：高风险。 `MEDIUM`：中等风险。 `LOW`：低风险。	"LOW"
result	Result	是	API请求结果，包含结果状态、结果码和结果消息。	{ "resultCode": "SUCCESS", "resultMsg": "success", "resultStatus": "S" }

HitResult字段说明

字段名称	数据类型	必须返回	描述	示例值
scanArgs	String	是	请求场景对应的引擎入参。	参考返回示例
scanResult	String	是	请求场景对应的引擎扫描结果。	"review"
hitReason	HitReason	否	请求命中名单原因。	{ "engineType": "SANCTION", "hitType": "name_match", "paramMatch": "John Doe", "recordMatch": "John Doe", "matchRate": 100, "matchStrategy": "s_person_name_common_src_full_name_similar" }
hitRecord	HitRecord	否	请求命中名单记录。	参考返回示例

HitReason字段说明

字段名称	数据类型	必须返回	描述	示例值
engineType	String	是	命中的引擎类型。 `SANCTION`：制裁名单引擎。 `PEP`：政治公共人物名单引擎。 `AM`：负面舆情名单引擎。 `CUSTOM`：客制化名单引擎。	"SANCTION"
hitType	String	是	命中类型。 `name_match`：名字匹配命中。 `id_match`：证件号匹配命中。	"name_match"
paramMatch	String	是	命中入参。	"John Doe"
recordMatch	String	是	命中名单记录字段值。	"John Doe"
matchRate	Int	是	匹配命中算法分数。	100
matchStrategy	String	是	匹配命中算法名。	"s_person_name_common_src_full_name_similar"

HitRecord字段说明

字段名称	数据类型	必须返回	描述	示例值
id	String	是	AML系统名单ID。	"584183"
version	String	是	AML系统名单版本。	1
originId	String	是	源名单记录ID。	"584183"
origin	String	是	源名单类型，包括`DOWJONES`和`WORLDCHECK`。	"DOWJONES"
type	String	是	名单记录类型。 `Person`：个人 `Entity`：企业	"Person"
action	String	是	源名单制作类型。 `add`：增加 `del`：删除 `chg`：修改	"add"
activeStatus	String	是	源名单记录状态。 `Active`：有效 `Inactive`：失效	"Active"
date	String	是	源名单记录的制作类型变化时间。	"05-Aug-2025"
category	String	否	WorldCheck名单专属一级分类。	"BANK"
subCategory	String	否	WorldCheck名单专属二级分类。	"PEP IO"
keywords	List<String>	否	WorldCheck名单专属名单分组信息。	["AMCBA-TERR"]
profileNotes	String	否	源名单中包含与人员或机构相关联的任何其他信息。	-
gender	String	否	性别，仅当`type`为`Person`时才返回该参数。 `Male`：男 `Female`：女 `Unknown`：未知性别	"Male"
deceased	String	是	该人物是否已死亡，仅当`type`为`Person`时才返回该参数。 `Yes`：已死亡 `No`：仍然健在	"No"
position	String	否	WorldCheck名单中描述个人或机构在社会和政治领域中的地位。	"Member of Legislature"
age	String	否	人物年龄，仅当`type`为`Person`时才返回该参数。	"32"
ageDate	String	否	人物年龄更新时间，仅当`type`为`Person`时才返回该参数。	"05-Aug-2025"
groups	List<String>	是	AML系统记录名单分组。	[ "DEMO_PERSON_SANCTION" ]
nameDetails	List<Name>	是	源名单记录的名字详情列表，该参数从多个维度记录了名字相关信息。	[ { "nameType": "Primary Name", "nameValueList": [ { "firstName": "John", "surname": "Doe" } ] } ]
descriptions	List<Description>	是	源名单结构描述。 `description1`：源名单记录分组第一层。 `description2`：源名单记录分组第二层。 `description3`：源名单记录分组第三层。	[ { "description1": "3", "description2": "1" } ]
dateDetails	List<Date>	否	源名单记录的日期详情。	[ { "dateType": "Date of Birth", "dateValueList": [ { "day": "10", "month": "May", "year": "1966" } ] } ]
sanctionsReferences	List<Reference>	否	制裁来源参考信息。	[ { "toDay": "10", "toMonth": "Sep", "toYear": "2019", "value": "Sanctioned for financial crimes" } ]
countryDetails	List<Country>	是	国家信息详情。	[ { "countryType": "Citizenship", "countryValueList": [ { "code": "example_country_code" } ] } ]
idNumberTypes	List<ID>	否	Person或Entity的ID相关信息。	[ { "idType": "Company Identification No.", "idValueList": [ { "value": "914403001922038216" } ] } ]
sourceDescription	List<Source>	否	Person或Entity的信息来源列表，其中`name`表示个人、机构或关联方的信息来源。	{ "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>	否	地址信息列表。	[ { "addressCountry": "kp" } ]
roleDetail	List<Roles>	否	人员职务或职业相关的详细列表。	参考返回示例
birthPlace	List<Place>	否	出生地信息列表，其中`name`表示出生地名。	[ { "name": "Wonsan,North Korea" } ]
images	List<Image>	否	Person图片信息链接列表，其中`url`表示图片URL。	[ { "url": "https://img.huffingtonpost.com/asset/5add68**.jpeg?ops=scalefit_630_noupscale" } ]
companyDetailsList	List<CompanyDetails>	否	制裁名单或官方名单中引用机构的地址值元素。	{ "AddressLine": "75 Danbury Road, Unit B5, Copps Hill Court", "AddressCity": "Ridgefield;Connecticut;06877", "AddressCountry": "USA" }
vesselDetailsList	List<VesselDetails>	否	船舶实体详细信息值列表。	[ { "VesselCallSign": "3E5918", "VesselType": "LNG Carrier", "VesselFlag": "PANA" }, { "VesselFlag": "NOTK" } ]

Name字段说明

字段名称

数据类型

必须返回

描述

示例值

nameType

String

是

源名单记录的名字类型。

"Primary Name"

nameValueList

List<NameValue>

是

源名单记录的名字值。

[

{

"firstName": "John",

"surname": "Doe"

}

]

NameValue字段说明

字段名称	数据类型	必须返回	描述	示例值
TitleHonorific	String	否	尊称	"Lord"
FirstName	String	否	名	"**"
MiddleName	String	否	中间名字	-
Surname	String	否	姓	"Doe"
MaidenName	String	否	婚前妇女的姓氏	-
Suffix	String	否	人名后缀	"Junior"
EntityName	String	否	企业名	"** Technologies Co., Ltd."
SingleStringName	String	否	统一格式的完整名称	-
OriginalScriptName	String	否	当地非拉丁文字的全名	"**技术有限公司"

Date字段说明

字段名称

数据类型

必须返回

描述

示例值

dateType

String

是

日期类型。

"Date of Birth"

dateValueList

List<DateValue>

是

日期详细值，其中dnotes是对日期的额外信息描述。

[

{

"day": "10",

"month": "May",

"year": "1966"

}

]

Reference字段说明

字段名称	数据类型	必须返回	描述	示例值
sinceDay	String	否	制裁来源参考起始日	"03"
sinceMonth	String	否	制裁来源参考起始月	"Jun"
sinceYear	String	否	制裁来源参考起始年	"2021"
toDay	String	否	制裁来源参考截止日	"10"
toMonth	String	否	制裁来源参考截止月	"Sep"
toYear	String	否	制裁来源参考截止年	"2019"
value	String	否	制裁来源参考键值	"Sanctioned for financial crimes"
name	String	否	制裁来源参考名	-

Country字段说明

字段名称

数据类型

必须返回

描述

示例值

countryType

String

是

国家信息类型。

"Country of Registratio"

countryValueList

List<CountryValue>

是

国家信息详细值，code表示国家代码。

[

{

"code": "cn"

}

]

ID字段说明

字段名称

数据类型

必须返回

描述

示例值

idType

String

是

ID类型

"Company Identification No."

idValueList

List<IDValue>

是

ID详细值

[

{

"value": "914403001922038216"

}

]

IDValue字段说明

字段名称	数据类型	必须返回	描述	示例值
value	String	是	ID值	"914403001922038216"
idNotes	String	否	ID值的额外信息描述	-

Address字段说明

字段名称	数据类型	必须返回	描述	示例值
addressLine	String	否	地址详情	"12 Throsby Street"
addressCity	String	否	城市	"Spearwood;Western Australia;6163"
addressCountry	String	否	国家	"AUSTR"
addressState	String	否	洲	-
url	String	否	URL地址	-

Role字段说明

字段名称

数据类型

必须返回

描述

示例值

roleType

String

是

职务类型。

"Primary Occupation"

occTitleList

List<OccTitle>

是

职位头衔方面的详细信息。

[

{

"occCat": "4",

"sinceDay": "05",

"sinceMonth": "Oct",

"sinceYear": "2021",

"toDay": "11",

"toMonth": "Jan",

"toYear": "2023",

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

}

]

OccTitle字段说明

字段名称	数据类型	必须返回	描述	示例值
sinceDay	String	否	起始日	"05"
sinceMonth	String	否	起始月	"Oct"
sinceYear	String	否	起始年	"2021"
toDay	String	否	截止日	"11"
toMonth	String	否	截止月	"Jan"
toYear	String	否	截止年	"2023"
occCat	String	否	职位编码	"4"
value	String	否	职位	"Secretary General, Ministry of Finance"

CompanyDetails字段说明

字段名称	数据类型	必须返回	描述	示例值
addressLine	String	否	地址详情	"12 Throsby Street"
addressCity	String	否	城市	"Spearwood;Western Australia;6163"
addressCountry	String	否	国家	"AUSTR"
url	String	否	地址URL	-

VesselDetails字段说明

字段名称	数据类型	必须返回	描述	示例值
vesselCallSign	String	否	船舶呼号值	"3E5918"
vesselType	String	否	船舶类型	"LNG Carrier"
vesselTonnage	String	否	船舶吨位	-
vesselGRT	String	否	船舶容积总吨	-
vesselOwner	String	否	船舶所有方名称	-
vesselFlag	String	否	船舶实体的Dow Jones地区代码标识	"PANA"

处理结果

根据请求结果执行下一步的响应动作，具体如下：

当result.resultStatus的值为S时，表示扫描信息接口调用成功。
当result.resultStatus的值为F时，表示扫描信息接口调用失败。请检查错误码获取有关该错误的更多信息，并分析导致该错误的原因。

API通用结果码

有关通用结果码的完整列表，请参见API通用结果码。

API特有结果码

AML名单筛查API的结果码已包含在API通用结果码中，具体可在API通用结果码中查看。

代码示例

请求示例

商户服务端发送的请求代码示例。

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

返回示例

AML服务器返回的响应代码示例。

未命中名单

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