Field name

Data  type

Max Length

Default Value

Description

bizId

String

32

-

Required. Unique business ID for tracing. For example, a sequence ID from the merchant's database.

Note: The ZOLOZ server does not enforce uniqueness. For better tracking, ensure your server guarantees unique business IDs.

transactionId

String

64

-

Required. The unique transaction ID that is returned in the response of the initialize API.

isReturnImage

String

1

N

Optional. Specifies whether to return image data in the response. Valid values:

• Y: Return image data. 

• N: Do not return image data. 

extraImageControlList

List<String>

[]

Optional. Additional document images to return when isReturnImage is "Y". Valid values: 

• FACE_EYE_CLOSE: Return a face image with closed eyes 

• DOC_FRONT_ANGLE: Return doc front page image captured with multiple angles.

• DOC_FRONT_FLASH: Return doc front page image captured with flashlight on.

• DOC_BACK_ANGLE: Return doc back page image captured with multiple angles.

• DOC_BACK_FLASH: Return doc back page image captured with flashlight on.

• CROPPED_FACE: Return an additional face image cropped from the original captured face image.

• CROPPED_FACE_FROM_DOC: Return the cropped face area of the captured doc image.

• MULTIACTIONS: Return all multi-action frame images collected at the edge side. If no actions are detected at the edge side or the actionFrame parameter in the initialize API is not set to MULTIACTIONS, the images will not be returned.

Note: Whether additional images are returned depends on whether these images have been successfully captured, which is determined by the following parameters in the initialize API:

• SDK type. If MULTIACTIONS is returned, ensure that the SDK version meets the following requirements:

  • iOS SDK: 1.6.2.250915171706 or later.

  • Android SDK: 2.0.5.250916100104 or later.

• docUiType in serviceLevel or productConfig. Different document types support different image capture types. You can refer to the serviceLevel field description for supported additional images by SDK type and serviceLevel value.

• Supported pages of the document and the pages that need to be captured

• cropFaceImage in productConfig

For example, when the SDK type is Native SDK, the servicelevel is REALID0002, and the pages are 1 and 2, the system will capture and return the front image of the document taken under flash illumination (DOC_FRONT_FLASH).

returnFiveCategorySpoofResult

String

1

N

Optional. Specifies whether to return document spoofing check results in 5 categories.

Valid values include:

• Y: document spoofing check result will be returned in 5 categories, including:

• TAMPER_CHECK

• MATERIAL_CHECK

• SCREEN_RECAPTURE_CHECK

• INFORMATION_CHECK

• SECURITY_FEATURE_CHECK

• N: document spoofing check result will be returned in 4 categories, including:

• TAMPER_CHECK

• MATERIAL_CHECK

• SCREEN_RECAPTURE_CHECK

• OTHER_CHECK

Field name

Data type

Description

result

Result

Required. API request result containing status and error codes.

ekycResult

String

Optional. Identity proofing process status. Available only whenresult.resultSatus is S. Possible values:

• Success: the identity proofing process runs successfully.

• Pending: theidentity proofing processis pending. 

• Failure: the identity proofing processfails, which indicates that at lease one of the document verification, face verification or risk control processing fails.

• InProcess:the identity proofing processis in progress.

• VoidCancelled:the identity proofing processis cancelled.

• VoidTimeout:the identity proofing process is timed out.

extBasicInfo

ExtBasicInfo

Optional. Basic real-name information. Available only when result.resultStatus is S. ExtBasicInfo. 

extFaceInfo

ExtFaceInfo

Detailed eKYC application face information. Only available when result.resultStatus is S.

Optional. Face verification details. Available only when result.resultStatus is S. ExtFaceInfo. 

extIdInfo

ExtIdInfo

Optional. Document verification details. Available only when result.resultStatus is S. ExtIDInfo. 

extRiskInfo

ExtRiskInfo

Optional. Risk control details. Available only when result.resultStatus is S. ExtRiskInfo. 

extCustomInfo

ExtCustomInfo

Optional. Customization details. Available only when result.resultStatus is S. ExtCustomInfo.

resultCode

resultSatus

Description

SUCCESS

S

The API call is successful.

INVALID_ARGUMENT

F

Input parameters are invalid. Check the result message or related log for details.

SYSTEM_ERROR

F

Other internal errors. Check the result message or related log for details.

Field name

Data type

Description

certType

String

ID type.

Specifies the type of the identity document. Required if the document verification process runs successfully.

certNo

String

ID number.

Specifies the ID number that is recognized from the identity document. Required if the document verification process runs successfully.

certName

String

ID name.

Specifies the name that is recognized from the identity document. Required if the document verification process runs successfully.

Field name

Data type

Description

ekycResultFace

String

Face verification result. Possible values:

• Success: The face verification process runs successfully.

• Pending: The face verification process is pending.

• Failure: The face verification process fails.

Required if the face verification processruns successfully.

faceScore

Integer

Score comparing the live face (selfie) against the document photo. Range: 0-100. 

Note:The faceScore field is returned only if the face image is collected successfully.

faceImg

String

The face selfie image, which is encoded in base64. This field is specified only when the value of the isReturnImage field in the request is set to Yand the face verification process runs successfully.

extraImages

Map<String,String>

Contain the extra face images specified in request.extraImageControlList.

Key is the value specified in request.extraImageControlList.

Value is the image content encoded in base64. If the requested image is not found, the value will be "".

faceQuality

Double

Quality score of the face selfie image. Range: 0-100. Returned if face verification runs successfully.

faceQualityPassed

Boolean

Required. The total quality result of the face image. Face quality detection supports multiple algorithms for detection, including face quality score, mask detection, and occlusion detection. Face quality score (i.e. whether the face is clear, complete etc) is detected by default, and more algorithms can be enabled according to business needs.

• true: The face quality score and all other detection modules have passed. If no additional modules are defined, only face quality assessment is checked by default.

• false: The face quality check failed. Either the face quality score or one of the other detection modules failed.

faceLivenessResult

String

Face liveness check result. Returns Success if no fake face attack is detected, orFailure otherwise.

estimatedAge

Integer

Estimated age based on the face selfie image.

Notes:

• The age estimation accuracy rate is 95% within a given age error range of 0-10 years.

• The value of this field is for reference only, which is not used for business judgement by ZOLOZ. If you need to intercept transactions for specific age, please add your own verification logic.

faceAttribute

FaceAttribute

Face attribute detection result. faceAttribute.

Note: This field is returned only when the faceAttributeCheck parameter is passed in and detectOpen is set as Y in the initialize API of Real ID.

actionCheckList

List<String>

Optional. Detected facial actions list.

deeperFaceResult

String

Optional. Specifies the deeper face detection result. It is returned when deeperMode is set to a value other than CLOSED. The following values will be returned:

• Success: No AIGC attack risk has been detected.

• Failure: AIGC attack risks have been detected.

deeperFaceResultDescription

String

Optional. Detailed description of the deeper face detection result when deeperMode is set to a value other than CLOSED and deeperFaceResult returns Failure.

deviceRisk

DeviceRisk

Optional. Returned device risk information. This field is only returned when you purchase Deeper product and the deeperMode parameter is not set to 'CLOSED' in the initialize API. Please refer to DeviceRisk for more details.

Field name

Data type

Description

occlusionMouthResult

String

Mouth occlusion detection result.

• true: Occlusion is present.

• false: No occlusion.

occlusionForeheadResult

String

Forehead occlusion detection result.

• true: Occlusion is present.

• false: No occlusion.

occlusionResult

String

Overall occlusion detection result.

• true: Occlusion is present.

• false: No occlusion.

occlusionChinResult

String

Specifies chin occlusion detection result.

• true: Occlusion is present.

• false: No occlusion.

occlusionEyesResult

String

Specifies eyes occlusion detection result.

• true: Occlusion is present.

• false: No occlusion.

occlusionNoseResult

String

Specifies nose occlusion detection result.

• true: Occlusion is present.

• false: No occlusion.

occlusionCheekResult

String

Specifies cheek occlusion detection result.

• true: Occlusion is present.

• false: No occlusion.

maskResult

String

Specifies mask detection result.

• true: Mask is present.

• false: No mask detected.

glassesResult

String

Specifies glasses detection result.

• true: Glasses is present.

• false: No glasses.

hatResult

String

Specifies hat detection result.

• true: Hat is present.

• false: No hat.

Field name

Data type

Description

riskLevel

Integer

Optional. Risk levels and corresponding recommendations:

• -1: Unable to identify face injection risk.Further assessment is recommended.

  Note: The Singapore site does not support this ability, and riskLevel will return-1.

• 0: Zero risk. No face injection risk is detected. Feel free to continue.

• 1: Low risk. Risk mark and monitoring are recommended.

• 2: Medium risk. Further security check is recommended, such as SMS verification, etc.

• 3: High risk. Direct interception is recommended.

Field name

Data type

Description

ekycResultDoc

String

Specifies the result of the document verification process. Possible values and their meanings are as below:

• Success: Thedocument verification processruns successfully.

• Pending: Thedocument verification processis pending.

• Failure: Thedocument verification processprocess fails.

Required if the document verification process runs successfully. 

docEdition

Integer

Specifies the edition of the identity document.

• 1~3: edition of the identity document. For more details, please see Document types supported and OCR results returned.

• 0: can not classify the identity document or wrong document type

• -1: unknown error

frontPageImg

String

The frontside image of the identity document. The image must be encoded in base64. This field is specified only when the value of the isReturnImage field in the request is set to Yand the document verification process runs successfully. 

backPageImg

String

The backside image of the identity document (if any). The image must be encoded in base64. This field is specified only when the value of the isReturnImage field in the request is set to Y, the document verification process runs successfully and it is required to upload the backside image of the identity document.

extraImages

Map<String,String>

Contain extra doc images specified in request.extraImageControlList and request.cropImage parameter.

Key is the value specified in request.extraImageControlList if request.extraImageControlList is not blank.

Possible Key values if request.cropImage is not blank:

• CROPPED_FRONT: return the cropped first page of the document

• CROPPED_BACK: return the cropped second page of the document

Value is the image content encoded in base64. If the requested image is not found, the value will be "".

ocrResult

Map

The OCR result, which contains information about the identity. Required if the document verification process runs successfully. Depending on the type of the identity document, different sets of identity information are recognized. For more information, see Supported document types and OCR result fields. 

ocrResultDetail

Map<String, OcrResultDetail>

OCR result details. This field is returned only when mrzVisualConsistencyCheck is provided in the initialize API.

spoofResult

Map

Optional. The spoofing check result, which contains information about the check results in terms of tampering, authenticity of the document material, and screen recapture. For more information, see spoofResult. 

extraSpoofResultDetails

List<ExtraSpoofResultDetail>

Optional. Extra document spoof detection result details. For more details, see extraSpoofResultDetails.

securityFeaturesResult

Map

Deprecated. See Hong Kong Document SecurityFeature Upgrade Notification - May 31, 2024.

docErrorDetails

String

Optional. Specifies the error details of the document verification process. Possible values and their meanings are as below:

• NO_REQUIRED_ID: The ID recognized from the uploaded image does not match the specified identity document type.

• BLUR: The uploaded identity document image is blurred.

• NO_FACE_DETECTED: A face that should have been recognized from the specified identity document is not detected from the uploaded image as expected.

• NOT_REAL_DOC: The uploaded identity document image is detected as fake.

• EXPOSURE: The uploaded identity document image is overexposed.

• UNKNOWN: All the other recognition errors. 

docErrorDescription

String

Optional. Specifies doc verification failure reason.

Field name

Data type

Description

TAMPER_CHECK

String

Required. Tampering check result. Returns Y if the document passes, or N if tampering is detected. 

MATERIAL_CHECK

String

Required. Material authenticity check result. Returns Y if the document passes, or N if the material fails (for example, black and white image). 

SCREEN_RECAPTURE_CHECK

String

Required. Screen recapture check result. Returns Y if the document passes, or N if a screen-recaptured image is detected. 

SECURITY_FEATURE_CHECK

String

(Optional) Currently only support HKIDs (both the old and new versions) and MyKad. Indicate whether the identity passed security feature check. Returned only if the "returnFiveCategorySpoofResult" parameter is set to "Y".

Possible values include:

Y: passed security feature check.

N: failed security feature check.

Field name

Data type

Description

name

String

Required. Indicate the name of the detailed document spoof check. For example, "landmarkCheckResult", "hologramCheckResult"

result

String

Required. Indicate the result of the detailed document spoof check.

Possible values include:

• Y: passed check

• N: failed check

spoofType

String

Required. Indicate the detailed document spoofing check category.

Possible values include:

• TAMPER_CHECK

• MATERIAL_CHECK

• SCREEN_RECAPTURE_CHECK

• INFORMATION_CHECK

• SECURITY_FEATURE_CHECK

components

Array

Required. Contain check result of each components. It will always be returned. If there is only one component check specified, the array will return one element.

components.name

String

Required. Component name.

Possible values are listed in the spoofing check details.

components.subResult

String

Required. Indicates the result of the component.

• Y:passed check

• N: failed check

Field name

Data type

Description

ekycResultRisk

String

Risk control result. Possible values:

• Success: The risk control process runs successfully.

• Pending: The risk control process is pending.

• Failure: The risk control process fails. 

strategyPassResult

String

Risk check result. Returned if risk control runs successfully. Possible values:

• PASS: the identity proofing process passes the risk check.

• VELOCITY_HIGH_RISK: indicates thathigh risks are detected by the risk control engine.

• ID_NETWORK_HIGH_RISK: indicates that a fake attack risk is detected through the ID network check. For example,a face is detected associated with multiple IDs, or an ID is detected associated with multiple faces.

  Note:This risk is not reported when similar faces are detected associated with the same ID (identified by ID number) or the same user (identified by userid).

• BLACKLIST_HIGH_RISK: indicates thathigh risks are detected by the blacklist scanning.

• AGE_MISMATCH_HIGH_RISK: indicates thathigh risks are detected during age verifications.

idNetworkDetails

String

Optional. Specifies the detailed information about the ID Network output, this field is a JSON string that comes from the JSON serialization result of the IdNetworkDetails structure, please refer to IdNetworkDetails.

Note: This field is specified only when the strategyPassResult field returns as ID_NETWORK_HIGH_RISK. 

otherRiskReasonDetails

String

Optional. Detailed outputs of risk engines other than ID Network. For example, for blacklist hits:

{

"BLACKLIST_HIGH_RISK": {

    "CERT": [

      {"listId":"xx","transactionId":"xx","itemId":xx,"similarScore":xx}

    ],

    "FACE":[

      {"listId":"xx","transactionId":"xx","itemId":"xx","similarScore":xx}

    ]

}

}

deeperRiskResult

String

Optional. Specifies the deeper risk detection result. It is returned when deeperMode is set to a value other than CLOSED.The following values will be returned:

• Success: No AIGC attack risk has been detected.

• Failure: AIGC attack risks have been detected.

deeperRiskResultDescription

String

Optional. Specifies the detail descriptions of the deeper risk detection result when deeperMode is set to a value other than CLOSED and deeperRiskResult returns Failure.

advancedIdnDetail

AdvancedIdnDetail

Optional. Detailed information output by IDN, see AdvancedIdnDetail for details.

Note: This parameter is only returned when the IDN feature is purchased and the checkAdvancedIdn field in the initialize is set to Y.

blackListDetails

List<BlackListDetail>

Optional. Detailed information output by the blacklist, see BlackListDetail

Note: This parameter is only returned when the blacklist feature is purchased and the checkBlacklist field in the initialize API is set to Y.

Field name

Data type

Description

ekyc_id

String

Optional. Deprecated field. Specifies eKYC ID.

mobile

String

Optional. Deprecated field. Specifies mobile phone number.

reason_code

Array

Optional. Specifies causes of risk:

• SIMILAR_FACE: Similar faces are detected associated with multiple users (identified by userid).

  Note:This risk is not reported when similar faces are detected associated with the same user (identified by userid).

• SAME_CERT_NO: An ID is detected associated with multiple users (identified by userid).

type

String

Optional. Specifies the type of risks triggered:

• Duplicated ID:Multiple documents for the same person.

• Fake ID: Tampering with document information.

score

String

Optional. Reserved field. When the value of type is Duplicated ID, this field will be returned.

Note: Please don't rely on this field.

user_id

String

Optional. Merchant user ID, or other identifiers that can be used to identify a specific user.

Risk type

Reason code

Description

Fake ID

SIMILAR_FACE

Same face, different ID numbers (same ID type).

SAME_CERT_NO

Same ID number (same ID type), different faces.

Duplicated ID

SIMILAR_FACE

Same face, different ID types.

Field name

Data type

Description

itemId

String

Optional. The record ID added to the ID Network database. Please keep this record ID for subsequent risk queries.

riskDetails

List<RiskDetail>

Optional. Current risks faced by the merchant. RiskDetail.

Field name

Data type

Description

Example

type

String

Returned risk type. For more details, see Risk introduction.

"IDFAKE"

subType

String

Returned sub-risk type. For more details, see Risk introduction.

"SameFaceDifferentIdNumber"

riskData

List<String>

Returned risk data with an itemId array.

["AIN20220727890199220364"]

riskDataDetails

List<RiskDataDetail>

Risk data details, see RiskDataDetail.

[

{

"itemId": "AIN20220727890199220364",

"sourceProductType": "RealID",

"sourceTransactionId": "G000000000FIA2026020200000012515624****"

}

]

Field name

Data type

Description

Example

itemId

String

Risk temId.

"AIN20220727890199220364"

sourceProductType

String

Source transactionId that triggered the IDN risk.

"RealID"

sourceTransactionId

String

Original transactionId associated with the risk itemId.

"G000000000FIA2026020200000012515624****"

Field name

Data type

Description

Example

listId

String

Target blacklist ID.

"10064"

itemId

String

Blacklist record ID.

"95c0e4e55d5cd5485edaa573d15e82**"

itemType

String

Type of blacklist record, including three types:

• FACE: Face blacklist.

• CERT: Certificate blacklist. Document blacklist containing items identified by document type and document number.

• DEVICE: Device blacklist.

"FACE"

similarScore

String

Similarity score, the higher the score, the greater the similarity.

99.99999999999999

transactionId

String

Source of the blacklist record, which is the information entered by the customer through the eKYC transactionId.

"G000000001FRL202410100000000109481109**"

Field name

Data type

Description

h5Degraded

String

Whether degraded mode is enabled. Valid values:

• Y: Downgrade mode is enabled.

• N: Downgrade mode is not enabled.

Note: This field is returned only when the allowDegradation parameter is set as Y in the initialize API of Real ID.

Date

Change log

Sep 20, 2024

A new parameter, blackListDetails, is added in ExtRiskInfo.

August 1, 2024

Deeper related interface information changes.

28 March, 2024

New output parameter faceAttribute is added.

30 November, 2023

IdNetworkDetailsand Introduction to risk types and reason codes are added

22 May, 2022

New input parameters of extraImageControlList, returnFiveCategorySpoofResult and new output parameters of extraImages, extraSpoofResultDetails are added.

23 October, 2020

OCR result keys for China identity card are added.

8 September, 2020

Two more types of identity documents are supported: Malaysia MyKad and Macau identity card. 

30 July, 2020

• A new parameter, securityFeaturesResult, is added in the ExtIdInfo field of the response.

• The following two new OCR result keys are added for both current and new HKIDs: 

• ISSUE_DATE

• LATEST_ISSUE_DATE 

21 May, 2020 

• A new OCR result key, SYMBOLS, is added for current and new HKID.

• A new key, OTHER_CHECK, is added in the spoofResult map. 

27 December, 2019

The letter case convention of the parameter name is updated. 

06 December, 2019

Released.