checkresult

2026-09-24 03:07

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/realid/reusable/checkresult
API Description: Used to query the runtime status and verification result of the Reusable RealID authentication process. Upon successful verification, it returns the Donor's document data and the face verification result of the Recipient's newly captured face.

Notes:

This API is a read-only query API and supports repeated calls with the same transactionId, meaning it is idempotent.
When the transaction status is InProcess, you may continue polling based on your business needs.
This interface does not return the recipientApplicantId. After a successful Reusable RealID verification, the system will asynchronously complete the Recipient applicant data consolidation. You can query the applicant information via the /api/v1/zoloz/applicant/query API.

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.	2026053000015
transactionId	String	64	Yes	-	Reusable RealID transaction ID, returned by the `/api/v1/zoloz/realid/reusable/initialize` API.	G000000005FRR2026053000001
isReturnImage	String	1	No	N	Whether to return Base64-encoded document and face images. Supported values: `Y`: Return images. `N`: Do not return images.	Y

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.	{ "resultCode": "SUCCESS", "resultMessage": "Success", "resultStatus": "S" }
ekycResult	String	No	The Reusable RealID identity verification status. Returned only when `result.resultStatus` is `S`. `Success`: Identity verification completed successfully. `Failure`: Identity verification failed. `InProcess`: Identity verification is in progress. `VoidCancelled`: The user cancelled the verification process. `VoidTimeout`: The verification process timed out.	Success
donorClientId	String	No	The Donor Client ID that provided the reused identity data. Returned only when `ekycResult` is `Success`.	donor_alg_hk_001
extBasicInfo	ExtBasicInfo	No	The basic identity information of the Donor's document. Returned only when `ekycResult` is `Success`.	{ "certType": "00000001003", "certNo": "P1234567" }
extIdInfo	ExtIdInfo	No	The detailed information of the Donor's document. Returned only when `ekycResult` is `Success`.	Refer to the ExtIdInfo Field Description section.
extFaceInfo	ExtFaceInfo	No	Verification result of the Recipient's newly captured face. The returned content varies depending on the ekycResult status: `Success`: Returns complete `extBasicInfo`, `extIdInfo`, `extFaceInfo`, and `donorClientId`. `Failure` / `VoidTimeout` / `VoidCancelled`: Returns face results only when a capture result already exists. `InProcess`: Returns no business information; please continue polling.	Refer to the ExtFaceInfo Field Description section.

ExtBasicInfo

Note: certType, certNo, and certName are returned only when document capture is successful.

Field Name	Data Type	Always Returned	Description	Example
certType	String	No	The Donor's document type code.	00000001003
docCategory	String	No	The document category from the Donor's existing document data. This field is result information, not a filtering parameter in Reusable initialize API. `PASSPORT` `DRIVING_LICENSE` `ID_CARD` `RESIDENCE_PERMIT` `VISA`	PASSPORT
certNo	String	No	The document number recognized from the Donor's document.	P1234567
certName	String	No	The name recognized from the Donor's document.	ZHANG SAN
certCountry	String	No	The issuing country or region of the Donor's document.	Hong Kong
certCountryCode	String	No	The issuing country or region code of the Donor's document.	HKG

ExtIdInfo

Field Name	Data Type	Always Returned	Description	Example
ekycResultDoc	String	No	The verification result of the Donor's document module. • `Success`: Document verification passed. • `Failure`: Document verification failed.	Success
ocrResult	Map	No	The OCR recognition results of the Donor's document. Different document types return different fields. For more information, see Document types supported and OCR results returned.	{ "ID_NUMBER": "P1234567", "NAME": "ZHANG SAN" }
ocrResultFormat	Map	No	The standardized OCR output results. For more information, see Notification on the Standardization of OCR Output Field Names.	{ "DOCUMENT_NUMBER": "P1234567" }
frontPageImg	String	No	The front page image of the Donor's 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 Donor's document, encoded in Base64. Returned only when `isReturnImage=Y` and the image exists.	"/9j/4AA..[omitted]..PxA="

ExtFaceInfo

Field Name	Data Type	Always Returned	Description	Example
ekycResultFace	String	No	The verification result of the Recipient's face module. • `Success`: Face verification passed. • `Failure`: Face verification failed.	Success
matchResult	String	No	The comparison result between the Recipient's newly captured face and the Donor's reference face. • `Success`: Face-to-ID comparison passed. • `Failure`: Face-to-ID comparison failed.	Success
faceScore	Integer	No	Face comparison score, ranging from 0 to 100.	91
faceQuality	Number	No	Face image quality score, ranging from 0 to 100.	88.5
faceQualityPassed	Boolean	No	Whether the face quality check passed. • `true`: Passed • `false`: Failed	true
faceLivenessResult	String	No	The face liveness detection result. • `Success`: No fake face attack detected. • `Failure`: Fake face attack detected.	Success
faceAttribute	FaceAttribute	No	Face attribute detection result. For example, `maskResult`, `glassesResult`, `occlusionResult`; the field values are all `true` or `false`. Returned only when the `faceAttributeCheck` parameter is passed in the initialize request of the Reusable RealID product and the `detectOpen` field is set to `Y`.	{ "maskResult": "false", "glassesResult": "true", "occlusionResult": "false" }
estimatedAge	Integer	No	The estimated age based on the face image. Note: This field is for reference only. ZOLOZ does not use the estimated age for business decisions. If you need to intercept transactions based on age, please add your own verification logic.	34
actionCheckItems	List	No	The list of facial action checks actually performed during this face capture process.	["FACEBLINK"]
faceImg	String	No	The Recipient's face image captured in this transaction, encoded in Base64. Returned only when `isReturnImage=Y` and the image exists.	"/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. Check ekycResult to determine the business status of Reusable RealID.
When result.resultCode = PROCESSING: The transaction is still being processed. You can continue polling.
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 checkresult API are listed in the table below.

resultCode	resultStatus	Description
SUCCESS	S	The API call is successful.
PROCESSING	S	The Reusable RealID transaction is still being processed, with `ekycResult = InProcess`.
INVALID_ARGUMENT	F	Invalid input parameters. Check the returned `resultMessage` for details on the invalid parameters.
SYSTEM_ERROR	F	Internal system error. For error details, check the returned `resultMessage`.

Note: Face liveness detection failure, face matching failure, user cancellation, or process timeout are not returned as independent API error codes. Please check ekycResult and extFaceInfo to determine these outcomes.

Sample

Request Sample

copy
{
    "bizId": "2026053000015", 
    "transactionId": "G000000005FRR2026053000001", 
    "isReturnImage": "Y"
}

Response Sample

Successful Response

copy
{
    "result": {
        "resultStatus": "S", 
        "resultCode": "SUCCESS", 
        "resultMessage": "Success"
    }, 
    "ekycResult": "Success", 
    "donorClientId": "donor_alg_hk_001", 
    "extBasicInfo": {
        "certType": "00000001003", 
        "docCategory": "PASSPORT", 
        "certNo": "P1234567", 
        "certName": "ZHANG SAN", 
        "certCountry": "Hong Kong", 
        "certCountryCode": "HKG"
    }, 
    "extIdInfo": {
        "ekycResultDoc": "Success", 
        "ocrResult": {
            "ID_NUMBER": "P1234567", 
            "NAME": "ZHANG SAN"
        }, 
        "ocrResultFormat": {
            "DOCUMENT_NUMBER": "P1234567"
        }, 
        "frontPageImg": "<base64-encoded document image>"
    }, 
    "extFaceInfo": {
        "ekycResultFace": "Success", 
        "matchResult": "Success", 
        "faceScore": 91, 
        "faceQuality": 88.5, 
        "faceQualityPassed": true, 
        "faceLivenessResult": "Success", 
        "faceAttribute": {
            "maskResult": "false", 
            "glassesResult": "true", 
            "occlusionResult": "false"
        }, 
        "actionCheckItems": [
            "FACEBLINK"
        ], 
        "faceImg": "<base64-encoded face image>"
    }
}

Processing Response

copy
{
    "result": {
        "resultStatus": "S", 
        "resultCode": "PROCESSING", 
        "resultMessage": "It is still under processing"
    }, 
    "ekycResult": "InProcess"
}

Failure Response

copy
{
    "result": {
        "resultStatus": "S", 
        "resultCode": "SUCCESS", 
        "resultMessage": "Success"
    }, 
    "ekycResult": "Failure", 
    "extFaceInfo": {
        "ekycResultFace": "Failure", 
        "matchResult": "Failure", 
        "faceLivenessResult": "Success"
    }
}