Date

Version

Release Notes

25 November, 2019

1.0.0

The first published version.

28 November, 2019

1.0.1

update api content

29 November, 2019

1.0.2

update ocr info

23 December, 2021

1.0.3

update image size limit

15 July, 2024

1.0.4

A new parameter, consistencyCheck, is added in productConfig.

27 Sep,2024

1.0.5

A new parameter, passportCountryCheck, is added in consistencyCheck of productConfig.

Field name

Data type

Max length

Mandatory

Default Value

Value Range

Description

Sample Value

bizId

string

32B

true

not null not empty string

Business unique ID for tracing purpose.

"trans-abc-1234"

docType

string

32B

false

null

not null not empty string

Document type.

• Supported category C documents: See Document types supported and OCR results returned
• Supported category B documents: See Business document types supported and OCR results returned

Note: docType specifies the specific document type, while autoDocTypes and autoDocCategory are used for automatic document classification. The three parameters are mutually exclusive; only one can be passed at a time.

"00000001003"

autoDocTypes

List<String>

200

false

null

Specifies list of document types. The parameters docType, autoDocTypes, and autoDocCategory are mutually exclusive; only one can be passed at a time.

• When autoDocTypes is provided, ZOLOZ will automatically classify the document uploaded.
  Notes：

• The passport auto-classification feature is supported, but it is only available in the Native SDK.
• Singapore Citizen card(00650000001) and PR card(00650000002) will be both classified as Singapore Citizen card.

• If the uploaded document could not be classified or it is not included in autoDocTypes list,  NO_REQUIRED_ID will be returned.

The value of items in autoDocTypes must be a valid docType. Supported document types, see Document types supported and OCR results returned.

["08520000001","08520000002"]

autoDocCategory

List<String>

-

true

null

Specifies list of document types. The parameters docType, autoDocTypes, and autoDocCategory are mutually exclusive; only one can be passed at a time.

• If you pass autoDocCategory, ZOLOZ will automatically classify the uploaded documents. The supported document categories are as follows:

• PASSPORT: Passport
• DRIVING_LICENSE: Driving License
• ID_CARD: ID Card
• RESIDENCE_PERMIT: Residence Permit
• VISA: Visa
• ALL: All documents

• If ZOLOZ cannot classify the uploaded document or the classified document type is not in autoDocCategory, it will return NO_REQUIRED_ID.

Note: Please be cautious that if autoDocCategory is in use, the docType classified could be a new type supported by ZOLOZ. It also means certType and docCategory in checkresult response could fall into a new type as we continue to expand the doc coverage globally. For example, when autoDocCategory in request is ALL, based on the doc submitted by user, after auto classification, the certType could be a new doc type (e.g. 00000001001 and NEW_CATEGORY). (For illustration only)

Please take necessary compatible actions for integration. For example, do not strongly validate the returned certType and docCategory.

"ID_CARD"

frontPageImage

string

5MB

true

not null not empty string

The front side of the document image supports Base64 encoded JPG/JPEG/PNG/BMP formats. 

"/9j/4AA..[omitted]..PxA="

backPageImage

string

5MB

false

The back side of the document image supports Base64 encoded JPG/JPEG/PNG/BMP formats.

"/9j/4AA..[omitted]..PxA="

operationMode

String

32

false

STANDARD

Specifies the operation mode where the identity proofing process runs. The following values are supported:

• CLOSED: All the algorithms and risk control rules are not applied. You can use this operation mode in the test phase so that the algorithms and risk controls rules do not affect the test process.
• STANDARD: A standard recommended level is applied. 
• LOOSE: A relatively looser level is applied. You can use this operation mode in low-risk scenarios.
• STRICT: A relatively stricter level is applied. You can use this operation mode in high-risk scenarios.

"STANDARD"

sceneCode

String

64

false

null

Specifies the business scene for data analysis purpose. If you want to distinguish the data performance of different scenes, it is recommended to set the sceneCode field to different values according to your business purpose; for example, login, riskVerify, payment, changePassword. Setting this value will not have business impacts.

"changePassword"

userId

String

64

false

null

Merchant user ID, or other identifiers that can be used to identify a specific user. For example, mobile phone number, email address and so on. It is strongly recommended to pre-desensitize the value of the userId field; for example, by hashing the value. 

"123456abcd"

extraImageControlList

List<String>

-

false

null

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

• CROPPED_FACE_FROM_DOC: return the cropped face area of the doc image.

Note: Extra images will only be returned if the document image provided in frontPageImage contains a face and is successfully cropped; otherwise, extraImages will return an empty string " ".

[

"CROPPED_FACE_FROM_DOC"

]

productConfig

ProductConfig

-

false

null

Optional. Specifies finer controls for the IDR product. For more information, see productConfig.

{

   "consistencyCheck": [

     {

       "type": "commonConsistencyCheck"

     },

     {

       "details": [

         "NAME",

         "SEX"

       ],

       "type": "mrzVisualConsistencyCheck"

     }

   ]

 }

Field name

Data type

Value range

Description

Supported ID / Country or Region / docType / OCR field to check

type

String

commonConsistencyCheck

Consistency check of OCR field within DOC spoofing check

Mykad / Malaysia / 00600000001 / ID_NUMBER

• front page: ID_NUMBER
• back page: ID_NUMBER_BACK first 12 digit

Field name

Data type

Value range

Description

Supported ID / Country or Region / docType / OCR field to check

type

String

mrzVisualConsistencyCheck

Consistency check of OCR field which has both MRZ (machine readable zone) and VIZ (visual inspection zone) within DOC spoofing check

-

details

List<String>

refer to supported ocr fileds of each docType

Specifies ocr field in details for consistency check.

• When type is set as mrzVisualConsistencyCheck,  details field is required and should not be null.
• Only allow to input OCR fields supported by the ID document.

MyVisa / Malaysia / 00600000011 /

• NAME
• SEX

Passport (both MRZ and VIZ) / CHN, HKG, TWN, MAC, PHL, SGP, MYS / 00000001006 /

• ID_NUMBER
• COUNTRY_CODE
• EXPIRY_DATE
• DATE_OF_BIRTH

Travel Permit for Hong Kong and Macau / China / 00860000011

• ID_NUMBER
• DATE_OF_EXPIRY

Field name

Data type

Mandatory

Value Range

Description

Sample Value

certType

String

false

ID type.

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

"00600000001"

docCategory

String

false

Specifies the type of the identity document.

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

"PASSPORT"

docEdition

Integer

false

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.

1

transactionId

string

false

transaction id

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.

"G000000005FID20200304000000000001570702"

recognitionResult

string

false

"Y"

"N"

recognition result

"Y"

recognitionErrorCode

string

false

NO_REQUIRED_ID

BLUR

NO_FACE_DETECTED

NOT_REAL_DOC
EXPOSURE

UNKNOWN

Details of document recognition failure:

• NO_REQUIRED_ID: The document image does not match the specified document type.
• BLUR: The document image is blurry.
• NO_FACE_DETECTED: No face detected on the document.
• NOT_REAL_DOC: Document anti-counterfeiting detection failed.
• EXPOSURE: The document image is overexposed.
• UNKNOWN: Other errors.

"BLUR"

recognitionErrorDescription

String

false

Specifies doc verification failure reason.

"passport country code check failed."

ocrResult

Map

false

ocr result map，please refer to appendix.

ocrResultFormat

Map

false

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>

false

OCR result details. This field is returned only when mrzVisualConsistencyCheck is provided.

Response Sample.

countryCode

String

false

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

"CHN"

spoofResult

Map

false

anti-spoofing result map，please refer to appendix.

{

"TAMPER_CHECK": "Y",

"MATERIAL_CHECK": "Y",

"SCREEN_RECAPTURE_CHECK": "Y",

"INFORMATION_CHECK": "Y",

"SECURITY_FEATURE_CHECK": "Y"

}

deeperResult

String

false

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

false

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.

"N"

result

CommonResult

true

common result, please refer to appendix.

extraImages

Map<String,String>

false

Optional. Specifies extra 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 "".

{

"CROPPED_FACE_FROM_DOC": "/9j/4AA..[omitted]..PxA="

}

Field name

Data type

Mandatory

Value Range

Description

Sample Value

resultCode

string

true

result code

"SUCCESS"

resultStatus

string

true

"S": successful

"F": failed

result status

"S"

resultMessage

string

true

result description

"success"

resultCode

Description

SUCCESS

success

SYSTEM_ERROR

other internal errors;

INVALID_ARGUMENT

input parameters are illegal;

Field name

Data type

Mandatory

Value Range

Description

Sample Value

TAMPER_CHECK

string

true

"Y": ok

"N": not ok

Check whether an ID is modified or not

"Y"

MATERIAL_CHECK

string

true

"Y": ok

"N": not ok

Check an ID's material is correct or not,

will return false once ID is black and white

"Y"

SCREEN_RECAPTURE_CHECK

string

true

"Y": ok

"N": not ok

Check if it is an ID recaptured from the screen

"Y"

INFORMATION_CHECK

string

false

"Y": ok

"N": not ok

Identity document information verification status.

Note: Currently, only Hong Kong Identity Cards are supported. The system verifies information on the identity card according to government regulations, such as the identity card number.

"Y"

SECURITY_FEATURE_CHECK

string

false

"Y": ok

"N": not ok

Identity document anti-counterfeit security feature detection status.

Note: Currently, only Hong Kong Identity Cards are supported. This detection verifies certain security features on the identity card to identify counterfeit documents.

"Y"