字段名称

数据类型

最大长度

是否必填

默认值

描述

示例值

bizId

String

32

是

-

业务ID，业务的唯一标识，用于追踪业务。例如，商户业务相关数据库中的序列号。

说明：ZOLOZ服务器不检查该字段的值是否唯一。为了更便捷地追踪业务，建议开启商户服务器，并确保业务ID的唯一性。

"1658894076638"

userId

String

64

否

null

商户的用户ID或其他可用于识别某一用户的标识，例如手机号码、电子邮件地址等。

建议对userId字段的值进行预脱敏，例如进行哈希处理。

"e9830710-0d70"

riskDetection

RiskDetection

-

否

null

风险检测。详细信息，请参见RiskDetection。

说明：存量历史数据批量入库时，为了提高入库执行效率，入库时可以不传该字段，先跳过风险检测，仅保存数据。后续可以通过risk query接口查询当前入库数据存在的风险。

{

   "riskTypes":[

     "IDFAKE",

     "DUPLICATE",

     "BATCH_REGISTER",

     "DEEPFAKE"

   ],

   "timeWindow":{

      "startTime":1651882535687,

      "endTime":1658902665000

   }

 }

checkAllianceRisk

String

-

否

N

是否查询联盟风险。取值如下：

• Y：同时查询联盟商户。
• N：仅查询当前商户。

"N"

imageInfo

ImageInfo

-

是

-

待传入的图片信息。详细信息，请参见ImageInfo。

说明：

• 目前只支持faceImage字段，docImage字段系统暂不支持。
• 图片格式为Base64编码字符串，且图片大小不超过5MB。

{ "docImage":"eA3AW/6dxn6QAAAABJRU5ErkJggg==...", "faceImage":"p+AY/b2OF/F1CxAAAAAElFTkSuQmCC..."

}

basicInfo

BasicInfo

-

否

null

用户的基本信息。详细信息，请参见BasicInfo。

说明：传入的basicInfo字段的值尽可能详细，风险检测阶段会比对传入的基础信息。

{

   "idType": "00000001003",  

   "idNumber": "46082119870811896X",  

   "certName": "李四",  

   "dateOfBirth": "19870811"

}

referenceId

String

64

否

null

引用ID，其他业务返回的ID值。

支持传入RealID或Face Capture的transactionId字段。当传入referenceId时，若客户未传入faceImage，系统将从transactionId所标识的交易中获取对应的人脸图片；若传入了faceImage，系统会优先使用faceImage中的人脸图片。basicInfo对象中的字段遵循相同的取值逻辑，即优先使用客户传入的数据。

"8365364ceddd411da027cdb15fea92ed"

scene

String

32

否

kyc

记录所属场景。取值如下：

• kyc：认证场景。
• verification：身份验证场景。

注意：查询的风险类型需要与场景保持一致；每种风险类型会在对应场景下的数据中查询。

"kyc"

字段名称

数据类型

最大长度

是否必填

默认值

描述

示例值

riskTypes

List<String>

-

否

[]

待查询的风险类型。支持以下四大类风险，系统会自动查询其包含的子风险。

• IDFAKE：身份冒用。
• DUPLICATE：重复认证。
• BATCH_REGISTER：批量注册。
• DEEPFAKE：人脸伪造。

[

     "IDFAKE",

     "DUPLICATE",

     "BATCH_REGISTER",

     "DEEPFAKE"

   ]

timeWindow

TimeWindow

-

否

最近180天

风险查询时间窗口，最长可查询180天的数据，默认查询最近180天的数据，详情请参见TimeWindow。

注意：系统单次扫描的数据量限制为50万条记录。如果在查询时间窗口范围内数据量超过50万条记录，系统会动态调整您所设置的时间窗口。

{ "startTime":1651882535687, "endTime":1658902665000 }

riskThreshold

Integer

-

否

1

指定风险查询的阈值，当历史有关联的风险交易笔数超过指定的阈值时将被拦截。相同的itemId只会计数一次。

支持传入大于等于1的任何整数，默认阈值为1。

1

字段名称

数据类型

最大长度

是否必填

默认值

描述

示例值

startTime

Long

-

否

null

风险查询起始时间，采用13位时间戳。

1651882535687

endTime

Long

-

否

null

风险查询结束时间，采用13位时间戳。

1658902665000

字段名称

数据类型

最大长度

是否必填

默认值

描述

示例值

docImage

String

-

否

null

待传入的证件图片（暂不支持该字段）。

"eA3AW/6dxn6QAAAABJRU5ErkJggg==..."

faceImage

String

-

否

null

待传入的人脸图片。

"p+AY/b2OF/F1CxAAAAAElFTkSuQmCC..."

字段名称

数据类型

最大长度

是否必填

默认值

描述

示例值

idType

String

32

否

null

证件类型。支持的证件类型，请参见支持的证件类型和返回的OCR结果。

"00000001003"

certName

String

32

否

null

姓名。

"李四"

idNumber

String

32

否

null

证件号码。

"46082119870811896X"

dateOfBirth

String

-

否

null

出生日期，格式为yyyyMMdd。

"19870811"

字段名称

数据类型

描述

示例值

result

Result

API请求结果，包含结果状态、结果码和结果消息。

{

   "resultStatus": "S",  

   "resultCode": "SUCCESS",  

   "resultMessage": "Success"

}

transactionId

String

IDN生成的唯一业务ID。

说明：仅当交易进入处理阶段后系统才会返回transactionId。如果在开始处理交易之前发生错误，系统不会返回transactionId。包括但不限于以下情况：

• 请求参数非法，例如入参格式错误或缺失必传参数。
• 请求未能成功到达服务器，例如网络问题或网关故障。
• 系统限流导致请求被拒绝。

"G00000000817636816"

itemId

String

本次新增数据的记录ID。

注意：请您保存好该记录ID，后续进行记录查询、风险查询、删除记录都需要使用该记录ID。

"AIN20220727890204890950"

hasRisk

Boolean

是否存在风险。

• true：存在风险。
• false：不存在风险。

true

riskDetails

List<RiskDetail>

风险详情。详细信息，请参见RiskDetail。

[ { "type":"IDFAKE", "subType":"SameFaceDifferentIdNumber", "riskData":[ "AIN20220727890199220364" ] }

allianceRiskDetails

List<RiskDetail>

联盟风险详情。详细信息，请参见RiskDetail。

[ { "type":"IDFAKE", "subType":"SameFaceDifferentIdNumber", "riskData":[ "AIN20220727890976220364" ] }

字段名称

数据类型

描述

示例值

type

String

风险类型。

"IDFAKE"

subType

String

子风险类型。

"SameFaceDifferentIdNumber"

riskData

List<String>

风险数据，内容为itemId数组。

["AIN20220727890199220364"]

riskDataDetails

List<RiskDataDetail>

风险数据详情，详见RiskDataDetail。

[

   {

       "itemId": "AIN20220727890199220364",  

       "faceSimilarScore": "90.0"

   }

]

字段名称

数据类型

必须返回

描述

示例值

itemId

String

否

风险itemId。

"AIN20220727890199220364"

faceSimilarScore

String

否

人脸相似分，分值越高相似度越高。

"90.0"