create

2026-08-26 08:47

Important Notice:

All request and response parameters are strictly subject to the official API documentation.
The API response may contain fields not defined in the documentation. These fields are for internal debugging purposes only and are not guaranteed to be stable or compatible. Do not rely on these fields in production environments. ZOLOZ reserves the right to modify or remove these fields at any time without prior notice.

Overview

API URL: POST /api/v1/zoloz/applicant/create
API Description: This API is used to create an applicant and return a unique identifier applicantId. This identifier can be used in subsequent calls to Applicant-related APIs and KYC data sharing capabilities.

Notes:

This API supports idempotent calls based on the merchant and userId. When the same merchant makes multiple calls with the same userId, the system returns the same applicantId.
The userId establishes a stable mapping between the merchant's user and the ZOLOZ applicant. The same userId under the same merchant must not be reassigned to different users.
Idempotent calls return the same applicantId, but each API call generates an independent transactionId. Therefore, repeated calls may return different transactionId values.

Request Parameters

Field Name	Data Type	Max Length	Required	Default Value	Description	Example
bizId	String	32	Yes	-	A unique business ID for tracing purposes. For example, the sequence ID from the merchant's business-related database. Note: The ZOLOZ server does not perform uniqueness checks on the value of this field. For better tracking, it is strongly recommended to enable the merchant server to guarantee the uniqueness of the business ID.	2026053000010
userId	String	64	Yes	-	The merchant-side user ID. It should be stable and unique under the same merchant. Once assigned to a user and successfully used to create an applicant, it must not be reassigned to another user.	u_donor_88001
email	String	255	No	-	The user's email address. If provided, it must conform to standard email format.	user@example.com
phone	String	50	No	-	The user's phone number.	+85291234567

Response Parameters

Field Name	Data Type	Always Returned	Description	Example
result	Result	Yes	The API request result, which contains the result status, result code, and result message.	{ "resultStatus": "S", "resultCode": "SUCCESS", "resultMessage": "Success" }
applicantId	String	No	The unique identifier of the ZOLOZ applicant. Returned only when `result.resultStatus` is `S`.	APHK_a1b2c3d4e5f6
transactionId	String	No	The transaction ID for this API call, which can be used for business tracking and troubleshooting. Note: The system will only return the `transactionId` after the transaction enters the processing stage. If an error occurs before the transaction begins processing, the system will not return a `transactionId`. This includes, but is not limited to, the following situations: Invalid request parameters, such as incorrect input format or missing required parameters. The request fails to reach the server successfully, such as due to network issues or gateway failures. The request is denied due to system rate limiting.	G000000005FID2020030400000000000157****

Response Rules

Processing Result	Returned Content
Creation Successful	Returns `result`, the newly created `applicantId`, and the `transactionId` for this call.
Idempotent Hit	Returns `result`, the existing `applicantId` for the `userId`, and the `transactionId` for this call.
Creation Failed	Returns `result` and the `transactionId` of this call, without returning the `applicantId`.

Result

For different request results, different actions will be performed. See the following for details:

When result.resultCode = SUCCESS: The applicant was created successfully, or the idempotent request matched an existing applicant. Please save the returned applicantId.
When result.resultStatus = F: Applicant creation failed. Check the returned resultCode and resultMessage to identify the issue with request parameters or system errors.

Common error codes

For the full list of common error codes, see the Common error codes section in the Error handling topic.

API-specific error codes

The error codes specific to the Reusable RealID create API are listed in the table below.

resultCode	resultStatus	Description
SUCCESS	S	The applicant was created successfully, or the system returned the applicant corresponding to the same `userId`.
INVALID_ARGUMENT	F	Invalid input parameters. Possible causes include missing required parameters, field length exceeded, invalid email format, etc. For detailed error information, check the returned `resultMessage`.
SYSTEM_ERROR	F	Internal system error. For error details, check the returned `resultMessage`.

Sample

Request Sample

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

Response Sample

Successful Response:

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

Idempotent Response:

When calling with the same userId again, the applicantId remains unchanged, and the transactionId is the transaction ID for this call.

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

Failure Response:

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