Field name

Data  type

Max Length

Default Value

Description

bizId

String

32

-

Required. A unique business ID for tracing purpose. For example，the sequence ID from the merchant's business-related database.

Note: The ZOLOZ server does not perform uniqueness check 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.

transactionId

String

64

-

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

isReturnImage

String

1

Y

Optional. Whether to return image data in the response. Values:

• Y：Return image data in the response.
• N：Do not return image data in the response.

extraImageControlList

List<String>

-

[]

Optional. Specifies whether to return extra document images. The following values are supported: 

• 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_FROM_DOC: return the cropped face area of the captured doc image.

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
• ServiceLevel
• Supported pages of the document and the pages that need to be captured
• cropFaceImageFromDoc in productConfig

Field name

Data type

Description

result

Result

Required. The API request result, which contains information about the result of the API request, such as status and error codes. 

extInfo

ExtInfo

Optional. Detailed information about document verification. This field is only available when the value of the result.resultStatus field is set to S. For more information, see ExtIDInfo. 

resultCode

resultSatus

Description

SUCCESS

S

User finished the transaction.

PROCESSING

S

User hasn't finish the whole flow.

INVALID_ARGUMENT

F

Input parameters are invalid. For more information about which parameter is invalid, check the result message or the related log. 

SYSTEM_ERROR

F

Other internal errors. For more information about the error details, check the result message or the related log. 

UNUSABLE

F

User is blocked by the cooldown strategy.

LIMIT_EXCEEDED

F

User tried too many times within the same transaction.

Field name

Data type

Description

Example

recognitionResult

String

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

• Y : The document verification process runs successfully.
• N : The document verification process process fails.

Required if the document verification process runs successfully. 

"Y"

certType

String

ID type.

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

"00600000001"

docCategory

String

ID type

• PASSPORT: Passport
• DRIVING_LICENSE: Driving License
• ID_CARD: ID Card
• RESIDENCE_PERMIT: Residence Permit
• VISA: Visa
• OTHERS: Other

"PASSPORT"

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.

2

imageContent

List<String>

The image of the identity document (if any). The image must be encoded in base64. This field is specified only when the document verification process runs successfully.

[

"base64string.....",

"base64string....."

]

extraImages

Map<String,String>

Optional. Specifies extra document images that should be returned, and this field can be 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 "".

{ "DOC_FRONT_ANGLE": "/9j/4AA..[omitted]..PxA=" }

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 Document types supported and OCR results returned. 

{

"ID_NUMBER": "12345",

"COUNTRY": "xxxxx",

"SEX": "M"

}

ocrResultFormat

Map

Optional. The standardized OCR output results can be found in the Notification on the Standardization of OCR Output Field Names.

{

"NUMBER": "12345",

"GENDER": "M"

}

ocrResultDetail

Map<String, OcrResultDetail>

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

Response Sample

countryCode

String

Optional. The country code recognized through OCR is returned only when the docCategory is a passport.

"CHN"

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. 

{

"TAMPER_CHECK": "Y",

"MATERIAL_CHECK": "Y",

"SCREEN_RECAPTURE_CHECK": "Y",

"INFORMATION_CHECK": "Y",

"SECURITY_FEATURE_CHECK": "Y"

}

recognitionErrorCode

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. 

"BLUR"

recognitionErrorDescription

String

Specifies doc verification failure reason. For instance, this field might return a message such as: 'passport country code check failed.'

"passport country code check failed."

uploadEnabledResult

String

Optional. Returns whether the end user chooses the upload mode. (Please note that the end user might not choose the upload mode even though the enableUpload parameter of the initialize API is set to Y)

• Y: upload mode is chosen.
• N: upload mode is not chosen.

"N"

deeperResult

String

Optional. Deeper document detection results.

The returned Deeper detection results are provided only when deeperMode is not CLOSED. The return values are as follows:

• Y: No AIGC attack risk detected.
• N: AIGC attack risk detected.

"N"

deeperResultDescription

String

Detailed description of Deeper document detection results. The detailed description of the Deeper detection results is provided only when deeperMode is not CLOSED and deeperResult is N.

"deepfake risk, AIGC feature blacklib"

Field name

Data type

Description

TAMPER_CHECK

String

Required. Specifies whether the input identity document passes the tampering check. If the identity document does not pass the check, which means it is detected as tampered, the value of N is returned; otherwise, Y is returned. 

MATERIAL_CHECK

String

Required. Specifies whether the material of the identity document passes the authenticity check. If the material of the identity document does not pass the check, for example, detected in black and white, the value of N is returned; otherwise, Y is returned. 

SCREEN_RECAPTURE_CHECK

String

Required. Specifies whether the identity document passes the screen recapture check. If the identity document does not pass the check, which means the image uploaded is detected as an image recaptured from a screen, the value of N is returned; otherwise, Y is returned. 

SECURITY_FEATURE_CHECK

String

Optional. Currently only support HK identity card. Validate some of the security features on the identity card to recognize fake cards.

INFORMATION_CHECK

String

Optional. Currently only support HK identity card. Validate the information on ID card such as ID number according to government rules.