create

2026-08-26 08:47

重要说明：

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

概览

API URL：POST /api/v1/zoloz/applicant/create
API 描述：该接口用于创建申请人并返回唯一标识applicantId。后续可使用该标识调用Applicant相关API及KYC数据共享能力。

说明：

该接口按照商户和userId支持幂等调用。同一商户使用相同的userId多次调用，系统将返回同一个applicantId。
userId用于建立商户用户与ZOLOZ申请人之间的稳定映射关系。同一商户下的同一个userId不可重复分配给不同用户。
幂等调用返回的applicantId固定不变，但每次API调用均会生成独立的transactionId，因此重复调用返回的transactionId可能不同。

请求参数

字段名称	数据类型	最大长度	是否必填	默认值	描述	示例值
bizId	String	32	是	-	业务ID，业务的唯一标识，用于追踪业务。例如，商户业务相关数据库中的序列号。说明：ZOLOZ不校验该值的唯一性，商户侧需自行保证该业务ID的唯一性。	2026053000010
userId	String	64	是	-	商户侧的用户ID。同一商户下应保持稳定且唯一，一旦分配给某用户并成功创建申请人后，不可再分配给其他用户。	u_donor_88001
email	String	255	否	-	用户邮箱地址，传入时须符合标准的邮箱格式。	user@example.com
phone	String	50	否	-	用户手机号码。	+85291234567

返回参数

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

返回规则

处理结果	返回内容
创建成功	返回 `result`、新创建的 `applicantId` 和本次调用的 `transactionId`。
幂等命中	返回 `result`、该 `userId` 已有的 `applicantId` 和本次调用的 `transactionId`。
创建失败	返回 `result`和本次调用的 `transactionId`，不返回 `applicantId`。

处理结果

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

当result.resultCode=SUCCESS时，表示申请人创建成功，或本次请求幂等命中已有申请人。请保存返回的applicantId。
当result.resultStatus=F时，表示申请人创建失败，请根据返回的resultCode和resultMessage排查请求参数或系统错误。

API通用结果码

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

API特有结果码

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

结果码	结果状态	描述
SUCCESS	S	申请人创建成功，或返回了相同 `userId` 对应的申请人。
INVALID_ARGUMENT	F	输入参数无效。可能原因包括：缺少必填参数、字段超长、邮箱格式无效等。具体错误信息请查看返回的`resultMessage`。
SYSTEM_ERROR	F	系统内部错误。有关错误详情，请查看返回的`resultMessage`。

代码示例

请求示例

copy
{
    "bizId": "2026053000010", 
    "userId": "u_donor_88001", 
    "email": "user@example.com", 
    "phone": "+85291234567"
}

返回示例

成功返回示例：

copy
{
    "result": {
        "resultStatus": "S", 
        "resultCode": "SUCCESS", 
        "resultMessage": "Success"
    }, 
    "applicantId": "APHK_a1b2c3d4e5f6", 
    "transactionId": "G000000005FID2020030400000000000157****"
}

幂等返回示例：

重复使用相同的 userId 调用时，applicantId 保持不变，transactionId 为本次调用对应的交易 ID。

copy
{
    "result": {
        "resultStatus": "S", 
        "resultCode": "SUCCESS", 
        "resultMessage": "Success"
    }, 
    "applicantId": "APHK_a1b2c3d4e5f6", 
    "transactionId": "G000000005FID2020030400000000000157****"
}

失败返回示例：

copy
{
    "result": {
        "resultStatus": "F", 
        "resultCode": "INVALID_ARGUMENT", 
        "resultMessage": "Invalid argument."
    }, 
    "transactionId": "G000000005FID2020030400000000000157****"
}