query

2026-08-26 08:47

重要说明：

所有请求及返回参数均严格以官网API文档为准。
API返回结果中可能包含未在文档中定义的字段。这些字段仅供内部调试使用，不保证稳定性及兼容性，请勿在生产环境中依赖这些字段，ZOLOZ保留随时修改或删除这些字段的权利，且无需另行通知。

概览

API URL：POST /api/v1/zoloz/applicant/query
API 描述：该接口用于查询当前商户下申请人的基本信息，以及与该申请人关联的证件和人脸 KYC 数据。支持通过 applicantId 或 userId 查询，并可选择是否返回图片数据。

说明：

该接口为只读查询接口，支持使用相同查询条件重复调用，即符合幂等性。
applicantId 与 userId 必须且只能提供一个。两者同时提供或同时不提供时，接口将返回 INVALID_ARGUMENT。
当 KYC 数据来源为 Reusable RealID 时，source=REUSE，并返回提供该数据的 donorClientId。
仅当 isReturnImage=Y 且存在对应图片时，才返回证件或人脸图片内容。

请求参数

字段名称	数据类型	最大长度	是否必填	默认值	描述	示例值
bizId	String	32	是	-	业务ID，业务的唯一标识，用于追踪业务。例如，商户业务相关数据库中的序列号。说明：ZOLOZ不校验该值的唯一性，商户侧需自行保证该业务ID的唯一性。	2026053000011
applicantId	String	50	是	-	ZOLOZ申请人ID。`applicantId`与`userId` 二选一传入。	APHK_a1b2c3d4e5f6
userId	String	64	是	-	商户侧的用户ID。`applicantId`与`userId` 二选一传入。	u_88001
isReturnImage	String	1	否	N	是否返回Base64编码的证件和人脸图片。取值： `Y`：返回 `N`：不返回	N

返回参数

字段名称	数据类型	必须返回	描述	示例值
result	Result	是	API请求结果，包含结果状态、结果码和结果消息。	{ "resultStatus": "S", "resultCode": "SUCCESS", "resultMessage": "Success" }
transactionId	String	否	本次调用返回的交易ID，可用于业务追踪和问题排查。说明：仅当交易进入处理阶段后系统才会返回`transactionId`。如果在开始处理交易之前发生错误，系统不会返回`transactionId`。包括但不限于以下情况：请求参数非法，例如入参格式错误或缺失必传参数。请求未能成功到达服务器，例如网络问题或网关故障。系统限流导致请求被拒绝。	G000000005FID2020030400000000000157****
applicantId	Applicant	否	申请人基本信息及其关联的证件、人脸数据。仅当`result.resultStatus`为`S`时返回。	参考Applicant字段说明

返回规则

处理结果	返回内容
查询成功	返回 `result`、`transactionId` 和 `applicant`。`documents`、`faces` 及其字段根据申请人的实际 KYC 数据返回。
申请人不存在	返回 `result` 和 `transactionId`，其中 `resultCode=APPLICANT_NOT_FOUND`，不返回 `applicant`。
查询失败	返回 `result` 和 `transactionId`，不返回 `applicant`。

Applicant字段说明

字段名称	数据类型	必须返回	描述	示例值
applicantId	String	否	ZOLOZ申请人ID。	APHK_a1b2c3d4e5f6
userId	String	否	商户侧的用户ID。	u_88001
email	String	否	用户邮箱地址。未设置时可能不返回或为空。	user@example.com
phone	String	否	用户手机号码。未设置时可能不返回或为空。	+85291234567
documents	List	否	与申请人关联的证件数据列表。	参考Document字段说明
faces	List	否	与申请人关联的人脸数据列表。	参考Face字段说明

Document字段说明

字段名称	数据类型	必须返回	描述	示例值
source	String	否	数据来源，支持`KYC`和`REUSE`。 `KYC`：通过RealID获得。 `REUSE`：通过Reusable RealID获得。其中，证件数据来源于Donor分享，人脸数据来源于Reusable RealID流程中的重新采集。	KYC
donorClientId	String	否	提供该证件数据的Donor Client ID。仅当 `source=REUSE` 时返回。	donor_client_001
isShareable	Boolean	否	该证件数据是否可用于创建 ShareToken。	true
certType	String	否	证件类型代码。	00000001003
certCategory	String	否	证件类别。 `PASSPORT`：护照 `DRIVING_LICENSE`：驾照 `ID_CARD`：身份证 `RESIDENCE_PERMIT`：居住证 `VISA`：签证	PASSPORT
certNo	String	否	证件号码。	P1234567
certName	String	否	证件姓名。注意：不同证件类型的OCR填写格式可能不一致，可能包含前导或尾随空格；如需精确匹配，建议使用`ocrResult`字段。	ZHANG SAN
certCountry	String	否	证件签发国家或地区名称。	Hong Kong
certCountryCode	String	否	证件签发国家或地区代码（ISO 3166-1 alpha-3标准）。	HKG
ocrResult	Map	否	证件OCR详细信息。不同证件类型返回的字段不同，详见RealID和ID Recognition支持的证件类型和返回的OCR结果。	{ "ID_NUMBER":"P1234567", "NAME":"ZHANG SAN" }
frontPageImg	String	否	证件正面图片，采用 Base64 编码。仅当 `isReturnImage=Y` 且存在对应图片时返回。	/9j/4AA..[omitted]..PxA=
backPageImg	String	否	证件背面图片，采用 Base64 编码。仅当 `isReturnImage=Y` 且存在对应图片时返回。	/9j/4AA..[omitted]..PxA=
extraImages	Map<String, String>	否	其他证件图片。仅当 `isReturnImage=Y` 且存在相关图片时返回。键为图片类型。值为 Base64 编码的图片内容。	{ "DOC_FRONT_FLASH":"/9j/4AA..[omitted]..PxA=" }

Face字段说明

字段名称	数据类型	必须返回	描述	示例值
`source`	String	否	数据来源，支持`KYC`和`REUSE`。 `KYC`：通过RealID获得。 `REUSE`：通过Reusable RealID获得。其中，证件数据来源于Donor分享，人脸数据来源于Reusable RealID流程中的重新采集。	`KYC`
`donorClientId`	String	否	提供该人脸数据的 Donor Client ID。仅当 `source=REUSE` 时返回。	`donor_client_001`
`isShareable`	Boolean	否	该人脸数据是否可用于创建 ShareToken。	`true`
`faceImg`	String	否	人脸图片，采用 Base64 编码。仅当 `isReturnImage=Y` 且存在对应图片时返回。	`/9j/4AA..[omitted]..PxA=`
`faceScore`	Integer	否	人脸比对分数。	`95`
`faceQuality`	Number	否	人脸质量分数。	`88`
`faceAttribute`	Map<String, String>	否	人脸属性检测结果，例如是否佩戴口罩、眼镜等。	`{ "mask":"no", "glasses":"none" }`
`extraImages`	Map<String, String>	否	其他人脸图片。仅当 `isReturnImage=Y` 且存在相关图片时返回。键为图片类型。值为 Base64 编码的图片内容。	`{ "FACE_EYE_CLOSE":"/9j/4AA..[omitted]..PxA=" }`

处理结果

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

当result.resultCode=SUCCESS时，表示查询成功，请读取 applicant 获取申请人及其关联的 KYC 数据。
当result.resultCode=APPLICANT_NOT_FOUND时，表示applicantId 或 userId 对应的申请人不存在，或不属于当前商户。
当result.resultStatus=F时，表示查询失败，请根据返回的 resultCode 和 resultMessage 排查具体原因。

API通用结果码

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

API特有结果码

Reusable RealID query API的结果码见下表。

结果码	结果状态	描述
SUCCESS	S	申请人查询成功。
APPLICANT_NOT_FOUND	F	`applicantId` 或 `userId` 对应的申请人不存在，或不属于当前商户。
INVALID_ARGUMENT	F	输入参数无效。可能原因包括：缺少必填参数、字段超长、`isReturnImage`取值非法（非Y/N）、`applicantId` 与 `userId` 未按二选一规则传入。具体错误信息请查看返回的`resultMessage`。
SYSTEM_ERROR	F	系统内部错误。有关错误详情，请查看返回的`resultMessage`。

代码示例

请求示例

使用 applicantId 查询，不返回图片：

copy
{
    "bizId": "2026053000011", 
    "applicantId": "APHK_a1b2c3d4e5f6", 
    "isReturnImage": "N"
}

使用 userId 查询并返回图片：

copy
{
    "bizId": "2026053000012", 
    "userId": "u_88001", 
    "isReturnImage": "Y"
}

返回示例

成功返回示例：

copy
{
    "result": {
        "resultStatus": "S", 
        "resultCode": "SUCCESS", 
        "resultMessage": "Success"
    }, 
    "transactionId": "G000000005FID20200304000000000001570702", 
    "applicant": {
        "applicantId": "APHK_a1b2c3d4e5f6", 
        "userId": "u_88001", 
        "email": "user@example.com", 
        "phone": "+85291234567", 
        "documents": [
            {
                "source": "KYC", 
                "isShareable": true, 
                "certType": "00000001003", 
                "certCategory": "PASSPORT", 
                "certNo": "P1234567", 
                "certName": "ZHANG SAN", 
                "certCountry": "Hong Kong", 
                "certCountryCode": "HKG", 
                "ocrResult": {
                    "ID_NUMBER": "P1234567", 
                    "NAME": "ZHANG SAN"
                }, 
                "frontPageImg": "<base64-encoded document image>"
            }
        ], 
        "faces": [
            {
                "source": "KYC", 
                "isShareable": true, 
                "faceScore": 95, 
                "faceQuality": 88, 
                "faceImg": "<base64-encoded face image>"
            }
        ]
    }
}

失败返回示例：

copy
{
    "result": {
        "resultStatus": "F", 
        "resultCode": "APPLICANT_NOT_FOUND", 
        "resultMessage": "Applicant does not exist."
    }, 
    "transactionId": "G000000005FID20200304000000000001570703"
}