Field name

Data type

Max length

Default Value

Description

Example

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.

"2017839040588699"

metaInfo

String

512

-

Required. The meta information about the SDK and the user's device. The value of this field is returned from the ZOLOZ SDK in the JSON string format, for example:

"{\"apdidToken\":\"69b74bfe-bf7f-4d3b-ac59-907ee09e7955\",\"appName\":\"com.zoloz.atomic.client\",\"appVersion\":\"1.0.9\",\"bioMetaInfo\":\"3.46.0:2916352,0\",\"deviceModel\":\"MI 6\",\"deviceType\":\"android\",\"osVersion\":\"9\",\"zimVer\":\"1.0.0\"}".

Note: Do not modify the returned value as it only needs to be passed through directly. When H5 mode is used, simply set the value as MOB_H5.

"{ \"deviceType\": \"android\", \"appVersion\": \"1.0.9\", \"osVersion\": \"9\", \"appName\": \"com.zoloz.atomic.client\", \"bioMetaInfo\": \"3.46.0:2916352,0\", \"apdidToken\": \"69b74bfe-bf7f-4d3b-ac59-907ee09e7955\", \"deviceModel\": \"MI 6\", \"zimVer\": \"1.0.0\" }"

userId

String

64

-

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

docType

String

16

-

Optional. Type of document.
For example, if the document to be uploaded is a passport, set the value of this attribute to 00000001003. For the document types that are supported,  see 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.

"08520000001"

autoDocTypes

List<String>

200

-

Optional. Specify the list of document types. The system automatically classifies uploaded documents. This parameter can be used alone or combined with the autoDocCountrycode parameter.

• Passport auto-classification is only supported by the Native SDK.
• 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 categories of document. 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. Specify the country or region to which the document belongs. Supports passing 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"]

autoDocPages

Map<String, String>

-

null

Optional. Specify the document pages tha need to scan and upload. This parameter is supported only when used in combination with document auto-classification parameters (autoDocTypes, autoDocCategory, and autoDocCountrycode). The parameter format is Key-Value pairs:

• Key: The document type passed.
• Value: Specify the pages to scan as follows:

• 1: Scan only the first page
• 1,2: Scan the first and second pages

For the maximum and default number of pages supported by different document types, see Document types supported and OCR results returned.

Note:

• If this parameter is not passed, the default value will be the default number of pages for the corresponding document type.
• If 2 pages need to be scanned, pass 1,2.
• When autoDocTypes and autoDocPages are passed simultaneously, the autoDocTypes must include all document types specified in autoDocPages.

{

"00630000032": "1",

"00630000004": "1,2"

}

pages

String

32

Default page count for document types

Optional. Specify the document pages tha need to be scan and upload. This parameter is supported only when used in combination with docType, multiple page numbers should be separated by commas.

• 1: Scan only the first page
• 1,2: Scan the first and second pages

For the maximum and default number of pages supported by different document types, see Document types supported and OCR results returned.

Note:

• If this field is not provided, it uses the default page count for the document type.
• If 2 pages need to be scanned, pass 1,2.
• When autoDocTypes , autoDocCategory or autoDocCountrycode is passed in, the pages parameter must be empty; Otherwise, it will return INVALID_ARGUMENT.

"1"

serviceLevel

String

32

IDRECOGNITION0002

This parameter is no longer recommended for use; please set the specific parameters in productConfig.

Optional. Three levels are supported:

• IDRECOGNITION0002 (default): basic anti-spoofing, which only captures a normal photo of the document.
• IDRECOGNITION0003: flashlight anti-spoofing. If this value is set, the ZOLOZ SDK automatically scans the identity document. The ZOLOZ server performs advanced spoofing checks. This level shall only be used in native SDK, as web SDK has technical limitations in operating the flashlight. If it is used in web SDK, the behaviour is unpredictable.
• IDRECOGNITION0005: multi-angle anti-spoofing. This level shall only be used in web SDK, the behaviour is unpredictable when used in native SDK. As of now, this level only supports HK identity cards, other document types may be supported in future when needed.

"IDRECOGNITION0002"

operationMode

String

32

STANDARD

This parameter is no longer recommended for use; please set the specific parameters in productConfig.

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

h5ModeConfig

Object

-

Optional. Specifies the configuration settings for H5 ID Recognition flow. For more information，see h5ModeConfig. 

{

"completeCallbackUrl": "https://sg-production-cdn.zoloz.com/page/zoloz-doc-fe/index.html",

"interruptCallbackUrl": "http://xxx.html"

}

productConfig

ProductConfig

-

-

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

Response Sample

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. 

transactionId

String

Optional. A unique transaction ID that is generated by the ZOLOZ server for the ID recognition process. This ID will be used as an input parameter for the ID recognition checkresult API request.

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.

clientCfg

String

Optional. The client configuration information, including parameters about SDK connection and behavior. The value of this field is specified only when the result.resultStatus field is "S". 

Field name

Data type

Max length

Default Value

Description

Example

cropDocImage

String

1

N

Optional. Specifies whether to crop the background of the captured DOC image. Valid values include:

• Y: Return an additional doc image cropped from the original captured doc image

• Note: A second additional doc image may be returned if two sides are captured i.e. front and back

• N: Default value. Do not crop

"Y"

landmarkCheck

Array

-

null

Optional. Specifies landmark check in the DOC spoofing check. For detailed inspection items, refer to the DOC spoofing check component.

Note: Landmark check is only applicable to MyKad

[

{"name":"kadPengenalan"},

{"name":"mykadLogo"},

{"name":"flagLogo"},

{"name":"mscLogo"},

{"name":"ghostFace"},

{"name":"hibiscusLogo"},

{"name":"coatOfArm"},

{"name":"twinTower"}

]

hologramCheck

Array

-

null

Optional. Specifies hologram check in the DOC spoofing check. For detailed inspection items, refer to the DOC spoofing check component.

Note: Hologram check is only applicable to MyKad.

[

{

"name": "hologram"

}

]

pageInfoCheck

Array

-

null

Optional. Specify page information check in the DOC spoofing check. For detailed inspection items, refer to the DOC spoofing check component.

Note: Page information check is only applicable to Hong Kong, China identity cards and Malaysia Mykad.

[

{"name":"id"},

{"name":"symbol"},

{"name":"name"}

]

consistencyCheck

List<ConsistencyCheckItem>

-

null

Optional. Specify whether to perform consistency checks. Consistency checks are only applicable for selected documents.

An array of supported information check components needs to be specified if consistency check is expected. To understand the valid values for this field, please refer to consistency check data structure.

[

{

"type": "commonConsistencyCheck"

},

{

"details": [

"NAME",

"SEX"

],

"type": "mrzVisualConsistencyCheck"

}

]

riskMode

String

10

STANDARD

Optional. This parameter refers to multi-dimensional risk control cooldown rule verification in ID recognition. It is used to intercept suspicious transactions. The values are as follows:

• CLOSED: Disable risk control cooldown rules. This level is applicable to testing scenarios where the testing process is not affected by risk control rules.
• STANDARD: A standard recommended level is applied.
• LOOSE: A relatively looser level is applied. You can use this risk detection mode in low-risk scenarios.
• STRICT: A relatively stricter level is applied. You can use this risk detection mode in high-risk scenarios.

"STANDARD"

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"

docUiType

String

20

• Native SDK: 2
• Web SDK: 3
  

Optional. This parameter refers to methods for taking ID photos. The values are as follows:

• 1: Self-capture. Users need to manually take ID photos, and it only has basic anti-spoofing capabilities.
• 2: Deep-scan, only for Native SDK. ZOLOZ SDK automatically aligns and captures ID photos, and it has advanced anti-spoofing capabilities such as intercepting printed color images.
• 3: Auto-scan, only for Web SDK. ZOLOZ SDK automatically aligns and captures ID photos, and it only has basic anti-spoofing capabilities. Auto-scan is recommended for WEB SDK because Auto-scan offers a better user experience and higher quality of document image compared to Self-scan.
• 4: Trace-scan, only for Native SDK. ZOLOZ SDK automatically captures ID photos when the document is detected within the camera range. It can improve user experience, but it only has basic anti-spoofing capabilities.

Note: This capture method is deprecated and no longer maintained.

• 5: Multi-angle, only for HKID in Web SDK. Users need to take two document photos from different angles. For the first photo, make the camera directly face the ID document and captures its photo. For the second, incline the ID document 30° against the camera and capture its photo.

Note: The Deeper feature relies on two collection methods: Deep-scan and Auto-scan. When the Deeper feature is enabled, please select the appropriate collection method based on your actual application scenario to ensure optimal detection performance. Use Deep-scan for the Native SDK and Auto-scan for the Web SDK. The detection effect will be greatly impacted if these two modes are not selected.

"2"

cropFaceImageFromDoc

String

1

N

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

• Y: Crop an additional face image from the original captured doc image.
• N: Do not crop.

"Y"

enableOCR

String

-

N

Optional. Whether to enable the OCR function. The values are as follows:
●  Y: Enabled
●  N: Not enabled
Note: You need to purchase the OCR product before you can use this feature.

"Y"

spoofMode

String

10

CLOSED

Optional. This parameter refers to document anti-spoofing levels, defined as follows:

• 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 Deeper level. For a detailed introduction to the Deeper detection function, see "What is Deeper". This parameter supports the following values:

• CLOSED: All Deeper capabilities are disabled, such as AIGC detection algorithms and terminal risk detection. If the business scenario does not require AIGC attack detection, do not enable this option.
• STANDARD: Recommended standard level.
• LOOSE: Relatively relaxed level, suitable for low-risk scenarios.
• STRICT: Relatively strict level, suitable for high-risk scenarios.

Note: You must purchase the Deeper product to use this function.

"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 viz / 00000001006 / COUNTRY_CODE

resultCode

resultStatus

Description

SUCCESS

S

The API call is successful.

F

High risks are detected. The user account is strategically cooled down by the risk engine.

F

The user account is blacklisted by the risk engine.

F

The device type is not supported.

OS_NOT_SUPPORT

F

The operating system of the device is not supported. 

SDKVERSION_NOT_SUPPORT

F

The version of the ZOLOZ SDK is not supported. 

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 that is returned and the related log. 

Field name

Data type

Max length

Default Value

Description

state

String

128

The value of the transactionId field.

Optional. An identifier that is used to recover the customer's context. You can set this field to any String value. The value is then passed as a parameter when the ZOLOZ SDK calls back to the merchant's application. If the value is not set, the value of the transactionId field is used. 

locale

String

16

en

Optional. Language of the web page, currently supports: 

• en (English)
• zh-CN (Simplified Chinese)
• zh-HK (Traditional Chinese) 
• jp (Japanese)
• th (Thai)
• es (Español)
• pt (Portuguese)
• fr (French)
• id (Indonesian)
• de (German)
• kr (Korean)
• vi(Vietnamese)

completeCallbackUrl

String

128

-

Required. Specifies the callback URL where the browser is redicted when the whole identity proofing process is completed. 

interruptCallbackUrl

String

128

-

Required. Specifies the callback URL where the browser is redirected when the process is interrupted. 

isIframe

String

1

N

Optional. If the Web Page need to be open in Iframe, this param should be set as Y.

Supported Value: Y / N

uiCfg

String

256

null

Optional. Custom UI configuration in JSON string format. Supports the following fields:

• titlebarbgcolor
• titlebartextcolor
• buttoncolor
• isDesktop: Indicates whether the document capture mode is initialized from the PC side.

• Y: Initialized from the PC side; users can upload document images via the PC or switch to the mobile side.Note: When isDesktop is Y, serviceLevel only supports IDRECOGNITION0002, and docUiType only supports 1; otherwise, the system will return INVALID_ARGUMENT.
• N: Initialized from the mobile side; users need to scan a QR code to switch to the mobile side. The default value is N.

For example:"{\"titlebarbgcolor\":\"#ffffff\",\"titlebartextcolor\":\"#000000\",\"buttoncolor\":\"#3696fd\", \"captureMode\":\"landscape\",\"isDesktop\":\"Y\"}"

enableUpload

String

1

N

Optional. Support for obtaining document images from uploaded files.
The following values are supported:

• Y: Enables uploading files to obtain document images.
• N: Disables uploading files to obtain document images.

Note:

• When enableUpload=Y and isDesktop=Y, the image upload function on the PC is enabled.
• When enableUpload=Y and isDesktop=N, the image upload function on the mobile side (Web SDK) is enabled.

• Mobile support includes both Web SDK and Native SDK, but only the Web SDK currently supports image upload.
• In this scenario, IDR will set the ID document verification result to Failure.