Item

IDN Lite

IDN

Some IDN functions.

All IDN functions.

Depends on users' usage and input to define the risk.

Retrival Time Span

Last 30 days

Supports configuration of retrival time span, including full database retrieval.

Risk Type

Fake ID:

• Same face different ID numbers
• Same ID number different faces

Duplicated ID:

• Same face different ID types

IDFAKE :

• SameFaceDifferentIdNumber
• SameFaceDifferentPerson
• SameIdDifferentFace
• SameIdDifferentPerson
• SamePersonDifferentFace
• SamePersonDifferentIdNumber

DUPLICATE:

• SameFaceDifferentIdType
• SameFaceDifferentUserId

BATCH_REGISTER:

• SameFaceBackgroundDifferentFace

Data Source

Supports data collected by RealID and other external data, but both need to be entered by calling the add API.

Database Management

Not supported

Supports Add, Delete, Retrieve and other operations in the database.

Retrieval Speed

Slow. It causes limited retrieval time span.

Fast. More advanced search engines are used to improve the retrieval speed.

Environments

Base API URIs

ZOLOZ portal address

Wireless Gateway Domain Name

Singapore Sandbox

https://sg-sandbox-api.zoloz.com

https://sg-sandbox-portal.zoloz.com/

https://sg-sandbox-api.zoloz.com

Singapore Production

https://sg-production-api.zoloz.com

https://sg-production-portal.zoloz.com/

https://sg-production-zmgs.zoloz.com

Hong Kong Production

https://hk-production-api.zoloz.net

https://hk-production-portal.zoloz.net/

https://hk-production-zmgs.zoloz.net

Indonesia Production

https://id-production-portal.zoloz.com/

https://id-production-zmgs.zoloz.com

Environment

Product

WEB SDK URL

Singapore Production/Sandbox

RealId

https://sg-production-cdn.zoloz.com/page/zoloz-realid-fe/index.html

FaceCapture/Connect

https://sg-production-cdn.zoloz.com/page/zoloz-face-fe/index.html

ID Recognition

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

Hong Kong Production/Sandbox

RealId

https://hk-production-cdn.zoloz.net/page/realid-fe/index.html

FaceCapture/Connect

https://hk-production-cdn.zoloz.net/page/face-fe/index.html

ID Recognition

https://hk-production-cdn.zoloz.net/page/doc-fe/index.html

Indonesia Production

RealId

https://id-production-cdn.zoloz.com/page/realid-fe/index.html

FaceCapture/Connect

https://id-production-cdn.zoloz.com/page/face-fe/index.html

https://id-production-cdn.zoloz.com/page/doc-fe/index.html

Collection Requirements

Detailed Description

Complete Document in Frame

Make sure that all four corners and edges of the document are within the collection frame.

Clear Document Image

Make sure the document image is clear and legible with no blurry areas.

Adequate Lighting

Make sure adequate lighting in the collection environment to effectively recognize the information on the document. Too bright or too dark environments may affect the verification results.

Avoid Glare

Avoid reflections from lights or ambient light, as glare on the document image can interfere with data processing and extraction.

No Obstructions

Make sure there are no obstructions on the document, and all information on the document is fully visible.

Avoid Tilt

Make sure the document is perfectly flat both horizontally and vertically, with no tilt.

Moderate Distance

Align the four edges of the document with the scanning frame. Being too far or too close can affect the collection results.

Appropriate Tilt Angle (for multi-angle versions only)

Align the four edges of the document with the tilted scanning frame. The tilt angle should generally not exceed 30 degrees.

Field Name

Product

Description

Reference

serviceLevel

Real ID

• REALID0001 :
  Users will be asked to take photos of their IDs manually.
  Using blink detection, the ZOLOZ server will perform a basic spoofing check and a basic liveness check.
• REALID0002 :
  The ID will be automatically scanned.
  Using blink detection, the ZOLOZ server will perform an advanced spoofing check and a basic liveness check.
• REALID0003:
  The ID will be automatically scanned. 
  Using 2 random multi-action detection, the ZOLOZ server will perform an advanced spoofing check and a liveness check. 
  Note: This service level is only available for Native SDK.
• REALID0004: 
  The ID will be automatically scanned even when held at an angle. 
  Using blink detection, the ZOLOZ server will perform a basic spoofing check and a basic liveness check.
• REALID0009:
  The ID will be automatically scanned. 
  Using blink detection, the ZOLOZ sever will perform an advanced spoofing check and a liveness check. This service level provides the ability to capture closed-eye images for Native SDK.
• REALID0011:
  The ID will be automatically scanned. 
  Using blink detection, the ZOLOZ sever will perform an advanced spoofing check and a liveness check. This service level provides the ability to capture closed-eye images for Web SDK.
• REALID0012:
  The ID will be automatically scanned. 
  Using blink detection, the ZOLOZ server will perform a basic spoofing check and a liveness check. 
  Note: This service level is only for Web SDK.
  

Refer to Real ID API Reference: initialize

Face Capture

• FACECAPTURE0001:
  Without using blink detection, a basic liveness check is performed.
• FACECAPTURE0002:
  Using blink detection, a middle-level liveness check is performed.
• FACECAPTURE0003:

       Using 2 random multi-action detection, a

       high-level liveness check is performed.

• Multi-action detection methods include: blinks, opened mouth, head facing upwards, head facing downwards, headshakes (left), headshakes (right).

• FACECAPTURE0005:
  Using blink detection, a full liveness check is performed. This service level also provides the ability to capture closed-eye images for Native SDK.
• FACECAPTURE0010:

       Using blink detection, a full liveness check is

       performed. This service level also provides the

       ability to capture closed-eye images for the Web

       SDK.

Refer to Face Capture API Reference:

initialize

ID Recognition

• IDRECOGNITION0002:
  Default value. Basic spoofing check.
• IDRECOGNITION0003:
  Flashlight spoofing check for Native SDK.
• IDRECOGNITION0005:
  Multi-angled spoofing check for Web SDK.
  Note: As of now, this service level only supports HK identity cards. 

Refer to ID Recognition API Reference:
initialize

Field name

Data type

Max length

Description

docUiType

String

20

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

• 1: Self-capture, default value for Web SDK. Users need to manually take ID photos,  and it only has basic anti-spoofing capabilities.
• 2: Deep-scan, default value for Native SDK and 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.
• 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.
• 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.

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 and risk control rules do not affect the testing process.
• STANDARD: Default value. A standard recommended level is applied.
• LOOSE: Reserved value, not currently supported for use.
• STRICT: Reserved value, not currently supported for use.

livenessMode

Optional. Specifies the liveness level for face liveness detection check. The following values are supported:

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

antiInjectionMode

String

Deprecated field, will no longer be maintained. To ensure API compatibility, this field will be retained. Optional. Specifies the anti-injection level for injection attack detection. Injection attack detection can effectively resist injection attacks using deepfakes i.e. face-swapping pictures or videos. The following values are supported:

• CLOSED: Default value. All the anti-injection algorithms are not applied. If the business scenario does not require injection attack detection, you do not need to enable it.
• STANDARD: A standard recommended level is applied.
• LOOSE: Reserved value, not currently supported for use.
• STRICT:Reserved value, not currently supported for use.

Note: Enabling injection attack detection will slightly increase false rejection rate and runtime. Please contact ZOLOZ technical support team before turning on this function. 

actionCheckItems

List<String>

Optional. User actions to be detected. For better user experience, it is not recommended to use two or more actions. The following values are supported:

• FACEBLINK: Default value. Requires the user to blink their eyes.
• MOUTHOPEN: Requires the user to open their mouth once.
• HEADSHAKE: Requires the user to shake their head. Left or right headshake will be specified for the user to perform.
• HEADLOWER: Requires the user to lower their head once.
• HEADRAISE: Requires the user to raise their head once.

Optional. Specifies whether user actions specified in actionCheckItems are in random order to be detected. Valid values include:

• Y: Random
• N: Default value. Not random, action detection is performed following the order in actionCheckItems.

actionFrame

Optional. This parameter refers to capturing other frame pictures, defined as follows:

• EYECLOSE: Set this value to return closed-eye frames collected during the blink detection method.

riskMode

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

• CLOSED: All algorithms are not applied. You can use this risk detection mode in the test phase so that the algorithms and risk control rules do not affect the testing process.
• STANDARD: Default value. 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.

idnThreshold

Deprecated field. Optional. The default threshold is 3. This parameter is used to check transactions in which one user uses different ID documents or one ID document is used  by different users. When the number of such transactions (from different userId) exceeds the threshold, the current transaction will be intercepted.  

Any integer larger than 0 is supported. 

Field name

Data type

Max length

Description

livenessMode

String

10

Optional. Specifies the liveness level for face liveness detection check. The following values are supported:

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

antiInjectionMode

String

10

Deprecated field, will no longer be maintained. To ensure API compatibility, this field will be retained. Optional. Specifies the anti-injection level for injection attack detection. Injection attack detection can effectively resist injection attacks using deepfakes i.e. face-swapping pictures or videos. The following values are supported:

• CLOSED: Default value. All the anti-injection algorithms are not applied. If the business scenario does not require injection attack detection, you do not need to enable it.
• STANDARD: A standard recommended level is applied.
• LOOSE: Reserved value, not currently supported for use.
• STRICT:Reserved value, not currently supported for use.

Note: Enabling injection attack detection will slightly increase false rejection rate and runtime. Please contact ZOLOZ technical support team before turning on this function. 

actionCheckItems

List<String>

Optional. User actions to be detected. For better user experience, it is not recommended to use two or more actions. The following values are supported:

• FACEBLINK: Default value. Requires the user to blink their eyes.
• MOUTHOPEN: Requires the user to open their mouth once.
• HEADSHAKE: Requires the user to shake their head. Left or right headshake will be specified for the user to perform.
• HEADLOWER: Requires the user to lower their head once.
• HEADRAISE: Requires the user to raise their head once.

actionRandom

String

1

Optional. Specifies whether user actions specified in actionCheckItems are in random order to be detected. Valid values include:

• Y: Random
• N: Default value. Not random, action detection is performed following the order in actionCheckItems.

actionFrame

List<String>

Optional. This parameter refers to capturing other frame pictures, defined as follows:

• EYECLOSE: Set this value to return closed-eye frames collected during the blink detection method.

Error

Possible reasons

Solution

SIGNATURE_INVALID

The extracted signature string does not match the to-be-validated content string.

Please refer to ZOLOZ's sample demo for the correct configuration and see Get API credentials ready for use.

ACCESS_DENIED

The account does not have access rights to this specific API at the present moment.

Only access to the Real ID API is enabled by default. For other product APIs such as ID Recognize and Face Compare, you will have to request for additional access.

Please contact ZOLOZ's technical support to enable access rights for other product APIs to be called.

PRODUCT_QUOTA_LIMIT

The test quota limit for API calls may have been reached.

Please contact ZOLOZ technical staff to handle your case.

You will need to provide sandbox environment information, such as the sg-sandbox environment, the clientID, as well as the email used.

HIGH_RISK

The risk control engine may have been triggered.

Avoid being detected as high risk when testing in the sandbox environment by disabling the risk controls. You can do this by setting request parameter operationMode of initialize API to different values or select corresponding Risk Level in the demo app:

Here is the details:

• To disable the Velocity feature, use 'STANDARD_VC_CLOSED' in the initialize API; or select 'Standard Risk Level 1' in the demo app.
• To disable the IDN feature, use 'STANDARD_IDN_CLOSED' in the initialize API; or select 'Standard Risk Level 2' in demo app.
• To disable both the Velocity and IDN features, use 'STANDARD_VC_IDN_CLOSED' in initialize API; or select 'Standard Risk Level 3' in the demo app.

       Your demo app should look like this:

Here are the definitions for IDN and Velocity:

• IDN: 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. For more details, see .
• Velocity: indicates that a fake attack risk is detected through the velocity check. For example, the number of attack (e.g. fake ID or liveness attacks) attempts by the same user (identified by userId, ID number or deviceId) in the past period of time reaches a certain threshold, the velocity check will not allow user further submission until the cooldown period has passed.

MERCHANT_NOT_FOUND

Error(s) may have occured regarding the clientID, endpoint/url, ZOLOZ public key, or merchant private key.

Please check that each of the following configurations are correct:

1. Check if the environment is correct. Please refer to Understand environments and service endpoints.

   ** Note that the portal environment has to be consistent with the endpoint/url environment.

2. Check that the spelling of the clientID is correct.
3. If you are still receiving the error, please check the configuration of the API keys i.e. the ZOLOZ public key or merchant private key.

   ** Note that this misconfiguration would usually result in an INVALID_SIGNATURE error rather than a MERCHANT_NOT_FOUND error.

PARAM_MISSING

The required request parameters are missing.

Please check that you are using the correct request parameter values according to the documentation.

If an optional request parameter has been passed in, the parameter value cannot be empty.

SYSTEM_ERROR

Two possible reasons could have occured:

1. The request parameter value is not supported
2. A system exception has been triggered.

1. Please check if you are using the correct request parameter values according to ZOLOZ API Reference. Optional request parameters cannot have empty string values.
2. If you are still unable to solve this issue, please provide the system error's request and response information to ZOLOZ's technical support.