Field name

Data type

Max length

Default Value

Description

Example

bizId

String

32B

-

Required. A unique ID maintained by the client for tracing purposes.

"trans-test-1234"

docType

String

32B

null

Optional. Type of document.

• 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 is mutually exclusive with autoDocTypes, autoDocCategory, and autoDocCountryCode, and can not be used together with any of them.

• Each of the four parameters—docType, autoDocTypes, autoDocCategory, and autoDocCountryCode—can be used independently on its own.

"00000001003"

autoDocTypes

List<String>

200

null

Optional. Specifies the document types to accept. The system automatically classifies uploaded documents. This parameter can be used alone or combined with the autoDocCountrycode parameter.

• Bank Card and Hong Kong/Macau Entry Permit do not support automatic categorization.

• If the system cannot classify the document or the classified document's country is not included in autoDocTypes, the checkresult API will return NO_REQUIRED_ID.

Supported document types, see Document types supported and OCR results returned.

[

"08520000001",

"08520000002"

]

autoDocCategory

List<String>

-

null

Optional. Specifies document type categories. The system automatically classifies uploaded documents. This parameter can be used alone or combined with the autoDocCountrycode parameter.

• 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 the system cannot classify the document or the classified document's country is not included in autoDocCategory, the checkresult API will return NO_REQUIRED_ID.

Note: When autoDocCategory is provided, the system may identify new document types and categories. In such cases, the certType and docCategory returned by the checkresult API might correspond to this newly identified country. This occurs because ZOLOZ is continuously expanding its global document coverage to support more document types.
For example, When autoDocCategory is set to ALL, the system automatically classifies the uploaded document. After classification, certType may return a new document type (e.g., 00000001001) and be categorized as NEW_CATEGORY.
To ensure your system smoothly adapts to newly supported document-issuing countries, we recommend implementing compatibility measures in advance—for example, avoiding strict validation of the returned certType and docCategory values.

"ID_CARD"

autoDocCountrycode

List<String>

300

null

Optional. Specifies the country or region of the document. Supports ALL or a three-letter country code conforming to the ISO 3166-1 alpha-3 standard. This parameter supports the following usage methods.

• When autoDocCountrycode is used independently: It indicates that the document type passed in belongs to a specific country or region.

• When autoDocCountrycode and autoDocCategory are used together, the system applies the intersection of both parameters. This indicates that the document type list is restricted to documents from a specific country.

For example: autoDocCategory=ID_CARD and DRIVING_LICENSE, autoDocCountrycode=PHL, This means that only Philippine ID cards and driver's license are allowed to pass through. Otherwise, the system will prompt a document type error.

• When autoDocCountrycode and autoDocTypes are used together, the system applies the intersection of both parameters.This indicates that the document type list is restricted to documents from a specific country.

Note:

• The autoDocTypes parameter must include a universal passport (00000001003 or 00000001006) to be used in combination; otherwise, the system will block the request.

• autoDocCountrycode must cover the country scope in the autoDocTypes list being passed in. Otherwise, the system will block the request.

For example:

• autoDocTypes= Universal Passports(00000001003 or 00000001006) and Philippine drivering license (00630000004), autoDocCountrycode=AUS, the system will block this request.

• autoDocTypes= Universal Passports(00000001003 or 00000001006) and Australian Permanent Resident Identity Card (00610000009), autoDocCountrycode=AUS, This means only Australian passports and permanent resident identity cards are allowed; otherwise, the system will return a document type error.

Note:

• If the system cannot classify the document or the classified document's country is not included in autoDocCountrycode, the checkresult API will return NO_REQUIRED_ID.

• When autoDocCountrycode is provided, the system may recognize a new document-issuing country. In such cases, the certCountry and certCountryCode returned by the checkresult API might correspond to this newly identified country. This occurs because ZOLOZ is continuously expanding its global document coverage to support more document types.

To ensure your system smoothly adapts to newly supported document-issuing countries, we recommend implementing compatibility measures in advance—for example, avoiding strict validation of the returned certType, docCategory, certCountry and certCountryCode values.

["CHN","PHI"]

frontPageImage

String

5MB

-

Required. The front image of the document, Base64 encoded in JPG, JPEG, PNG, or BMP format.

Note: The total size of frontPageImage and backPageImage must not exceed 5MB. If the images are too large, it is recommended to compress them before uploading to avoid system errors.

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

backPageImage

String

5MB

-

Optional. Required. The back image of the document, Base64 encoded in JPG, JPEG, PNG, or BMP format.

Note: The total size of frontPageImage and backPageImage must not exceed 5MB. If the images are too large, it is recommended to compress them before uploading to avoid system errors.

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

operationMode

String

32

STANDARD

Optional. Specifies the identity proofing operation mode. 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

null

Optional. Specifies the business scene for data analysis. To distinguish data performance across different scenes, set 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

null

Optional. Merchant user ID or other user identifier, such as a mobile phone number or email address. Pre-desensitizing the value (for example, by hashing) is strongly recommended.

"trans-abc-1234"

productConfig

ProductConfig

-

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

Max length

Default Value

Description

Example

pageInfoCheck

Array

-

null

Optional. Specifies page information checks within DOC spoofing check. For detailed inspection items, see the DOC spoofing check component.

Note: Page information check is only applicable to the following document types:

• Hong Kong Identity Cards

• Malaysia Mykad

• Singapore Citizen Card

• Singapore Permanent Resident Card

[

{"name":"id"},

{"name":"symbol"},

{"name":"name"}

]

consistencyCheck

List<ConsistencyCheckItem>

-

null

Optional. Specifies whether to perform a consistency check. Consistency checks apply only to specific fields of certain documents.
Specify an array of information check components if a consistency check is expected. For valid values, see consistency check data structure.

[

{

"type": "commonConsistencyCheck"

},

{

"details": [

"NAME",

"SEX"

],

"type": "mrzVisualConsistencyCheck"

},

{

"valueRange": [

"CHN",

"PHL"

],

"type": "passportCountryCheck"

}

]

allowExpiredDocument

String

-

Different document types have different default values:

• Y: This is the default value for all documents except Passport (docType=00000001003).

• N: This is the default value for Passport (docType=00000001003).

Optional. Specifies whether expired documents are allowed. The following values are supported:

• Y: Allow expired documents.

• N: Pause ID Recognition process when an expired document is detected.

Note:

• If a value other than Y or N is provided, the system will return INVALID_ARGUMENT.

• For the Hong Kong first-generation ID card (docType=08520000001), the logic of intercepting expired documents will strictly follow the requirements of the Hong Kong government's identity document replacement process.

"N"

cropFaceImageFromDoc

String

1

N

Optional. Specifies whether to crop the face area of the captured doc image. Valid values include:

• Y: Crop an additional face image from the doc image

• N: Default value. Do not crop

"Y"

enableOCR

String

-

N

Optional. Whether to enable the OCR function. The values are as follows:

• Y: Enabled

• N: Not enabled

"Y"

spoofMode

tring

10

CLOSED

Optional. Document anti-spoofing level. Valid values:

• CLOSED: All algorithms are not applied. You can use this anti-spoofing detection mode in the test phase so that the algorithms do not affect the testing process.

• STANDARD: A standard recommended level is applied.

• LOOSE: Reserved value, not currently supported for use.

• STRICT: Reserved value, not currently supported for use.

Note: You need to purchase the Spoof product before you can use this feature.

"STANDARD"

deeperMode

String

10

CLOSED

Optional. AIGC attack detection level (Deeper). For more information, see What Is Deeper.

This parameter supports the following values:

• Closed: All capabilities of Deeper are disabled, including AIGC detection algorithms and endpoint risk detection. If the business scenario does not require AIGC attack detection, there is no need to enable it.

• Standard: Recommended standard mode.

• Loose: Relatively lenient mode, suitable for low-risk scenarios.

• Strict: Relatively strict mode, suitable for high-risk scenarios.

"STANDARD"

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

Specify 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) / All countries or regions / 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

Value range

Description

Supported ID / Country or Region / docType / OCR field to check / default country code

type

String

passportCountryCheck

Checks that the COUNTRY_CODE in the OCR result is consistent with the country detected by the system.

valueRange

List<String>

Each value should be the same as

the default country code.

The COUNTRY_CODE in the OCR result should be within the valueRange.

When the type is set to passportCountryCheck, the valueRange field must be provided. For the supported valueRange of each document, please refer to

Document types supported and OCR results returned

For below docTypes, valueRange should be a list of its default country or region code

• China Passport / 00860000888 / COUNTRY_CODE / CHN

• China Taiwan Passport / 08860000002 / COUNTRY_CODE / TWN

• China Macao Passport / 08530000002 / COUNTRY_CODE / CHN

• Philippines Old Passport / 00630000031 / COUNTRY_CODE / PHL

• Philippines New Passport /00630000032 / COUNTRY_CODE / PHL

Each value should comply with ISO_3166-1_alpha-3

For below docTypes, valueRange should be a list, and each item should comply with ISO_3166-1_alpha-3

• Internaltional Passport / 00000001003 / COUNTRY_CODE

• Passport （with MRZ and VIZ) / 00000001006 / COUNTRY_CODE

Field name

Data type

Description

Example

result

CommonResult

Required. Common result. For more information, see Appendix.

{

"resultCode": "PROCESSING",

"resultStatus": "S",

"resultMessage": "It is still under processing"

}

transactionId

String

Required. 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.

"G000000005FID2020030400000000000157****"

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;