query

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/query
API Description: This API is used to query the basic information of an applicant under the current merchant, as well as the document and face KYC data associated with the applicant. It supports querying by either applicantId or userId, and optionally allows returning image data.

Notes:

This API is a read-only query API and supports repeated calls with the same query criteria, meaning it is idempotent.
Exactly one of applicantId or userId must be provided. If both are provided or neither is provided, the API returns INVALID_ARGUMENT.
When the KYC data source is Reusable RealID, source is set to REUSE and the donorClientId that provided the data is returned.
Document and face images are returned only when isReturnImage=Y and the corresponding images exist.

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.	2026053000011
applicantId	String	50	Yes	-	The ZOLOZ applicant ID. Either `applicantId` or `userId` must be provided.	APHK_a1b2c3d4e5f6
userId	String	64	Yes	-	The merchant-side user ID. Either `applicantId` or `userId` must be provided.	u_88001
isReturnImage	String	1	No	N	Whether to return Base64-encoded document and face images. Supported values: `Y`: Return images. `N`: Do not return images.	N

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" }
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****
applicantId	Applicant	No	The applicant's basic information and the associated document and face data. Returned only when `result.resultStatus` is `S`.	Refer to the Applicant Field Description section.

Response Rules

Processing Result	Returned Content
Query Successful	Returns `result`, `transactionId`, and `applicant`. The `documents`, `faces`, and their fields are returned based on the applicant's actual KYC data.
Applicant Not Found	Returns `result` and `transactionId` with `resultCode=APPLICANT_NOT_FOUND`. Does not return `applicant`.
Query Failed	Returns `result` and `transactionId`. Does not return `applicant`.

Applicant Field Description

Field Name	Data Type	Always Returned	Description	Example
applicantId	String	No	The ZOLOZ applicant ID.	APHK_a1b2c3d4e5f6
userId	String	No	The merchant-side user ID.	u_88001
email	String	No	The user's email address. May not be returned or may be empty if not set.	user@example.com
phone	String	No	The user's phone number. May not be returned or may be empty if not set.	+85291234567
documents	List	No	The list of document data associated with the applicant.	Refer to the Document Field Description section.
faces	List	No	The list of face data associated with the applicant.	Refer to the Face Field Description section.

Document Field Description

Field Name	Data Type	Always Returned	Description	Example
source	String	No	The data source. Supported values: `KYC`: Obtained through the RealID process. `REUSE`: Obtained through the Reusable RealID process. Specifically, the document data is sourced from the Donor's sharing, while the face data is recaptured during the Reusable RealID process.	KYC
donorClientId	String	No	The Donor Client ID that provided this document data. Returned only when `source=REUSE`.	donor_client_001
isShareable	Boolean	No	Whether this document data can be used to create a ShareToken.	true
certType	String	No	The document type code.	00000001003
certCategory	String	No	The document category. `PASSPORT` `DRIVING_LICENSE` `ID_CARD` `RESIDENCE_PERMIT` `VISA`	PASSPORT
certNo	String	No	Document number.	P1234567
certName	String	No	Name on the document. Note: The OCR format may vary across different document types and may contain leading or trailing spaces. For exact matching, it is recommended to use the `ocrResult` field.	ZHANG SAN
certCountry	String	No	Issuing country or region name of the document.	Hong Kong
certCountryCode	String	No	Issuing country or region code (ISO 3166-1 alpha-3 standard).	HKG
ocrResult	Map	No	The document OCR result details. Different document types return different fields. For more information, see Document types supported and OCR results returned.	{ "ID_NUMBER":"P1234567", "NAME":"ZHANG SAN" }
frontPageImg	String	No	The front page image of the document, encoded in Base64. Returned only when `isReturnImage=Y` and the image exists.	/9j/4AA..[omitted]..PxA=
backPageImg	String	No	The back page image of the document, encoded in Base64. Returned only when `isReturnImage=Y` and the image exists.	/9j/4AA..[omitted]..PxA=
extraImages	Map<String, String>	No	Additional document images. Returned only when `isReturnImage=Y` and the relevant images exist. The key is the image type. The value is the Base64-encoded image content.	{ "DOC_FRONT_FLASH":"/9j/4AA..[omitted]..PxA=" }

Face Field Description

Field Name	Data Type	Always Returned	Description	Example
`source`	String	No	The data source. Supported values: `KYC`: Obtained through the RealID process. `REUSE`: Obtained through the Reusable RealID process. Specifically, the document data is sourced from the Donor's sharing, while the face data is recaptured during the Reusable RealID process.	`KYC`
`donorClientId`	String	No	The Donor Client ID that provided this face data. Returned only when `source=REUSE`.	`donor_client_001`
`isShareable`	Boolean	No	Whether this face data can be used to create a ShareToken.	`true`
`faceImg`	String	No	The face image, encoded in Base64. Returned only when `isReturnImage=Y` and the image exists.	`/9j/4AA..[omitted]..PxA=`
`faceScore`	Integer	No	Face comparison score.	`95`
`faceQuality`	Number	No	Face quality score.	`88`
`faceAttribute`	Map<String, String>	No	Face attribute detection results, such as whether a mask or glasses are worn.	`{ "mask":"no", "glasses":"none" }`
`extraImages`	Map<String, String>	No	Additional face images. Returned only when isReturnImage=Y and the relevant images exist. The key is the image type. The value is the Base64-encoded image content.	`{ "FACE_EYE_CLOSE":"/9j/4AA..[omitted]..PxA=" }`

Result

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

When result.resultCode = SUCCESS: The query was successful. Read applicant to obtain the applicant and its associated KYC data.
When result.resultCode = APPLICANT_NOT_FOUND: The applicant corresponding to the provided applicantId or userId does not exist or does not belong to the current merchant.
When result.resultStatus = F: The query failed. Check the returned resultCode and resultMessage to identify the specific cause.

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 query API are listed in the table below.

resultCode	resultStatus	Description
SUCCESS	S	Applicant query successful.
APPLICANT_NOT_FOUND	F	The applicant corresponding to the provided `applicantId` or `userId` does not exist or does not belong to the current merchant.
INVALID_ARGUMENT	F	Invalid input parameters. Possible causes include missing required parameters, field length exceeded, invalid `isReturnImage` value (not Y or N), or failure to provide exactly one of `applicantId` or `userId`. For detailed error information, check the returned `resultMessage`.
SYSTEM_ERROR	F	Internal system error. For error details, check the returned `resultMessage`.

Sample

Request Sample

Query by applicantId (without returning images)

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

Query by userId (returning images)

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

Response Sample

Successful Response

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

Failure Response

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