initialize

2025-05-07 07:14

POST/api/v1/zoloz/realid/initialize

The ZOLOZ Real ID initialize API is used to initialize the identity proofing process in ZOLOZ. A unique transaction ID is generated for the identity proofing process and used in all the subsequent interactions with the ZOLOZ server. This API is not idempotent.

structure

Request parameters

Field name	Data type	Max length	Default Value	Description
bizId	String	32	-	Required. A unique business ID for tracing purposes. For example, the sequence ID from the merchant's business-related database. Note: The ZOLOZ server does not perform uniqueness checks 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.
metaInfo	String	512	-	Required. The meta information about the SDK and the user's device. When the App SDK mode is used, its value comes from the ZOLOZ SDK in 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`.
flowType	String	32	-	Required. Specifies the type of the identity proofing flow. The following values are supported: `REALIDLITE_KYC` : Specifies this value when the App SDK mode is used. `H5_REALIDLITE_KYC` : Specifies this value when the H5 mode is used.
docType	String	16	null	Optional. Type of document. For example, if the document to be uploaded is a passport, set the value of this attribute to 00000001003. The value of this field must not be null or an empty string. For the document types that are supported by Real ID, see Document types supported and OCR results returned. Note: `docType` is used to specify the specific type of document, while `autoDocTypes` and `autoDocCategory` are used for automatic classification of documents. The three parameters are mutually exclusive, and only one of them is supported for input at a time.
autoDocTypes	List<String>	200	null	Optional. Specify the list of document types. The parameters docType, autoDocTypes, and autoDocCategory are mutually exclusive and only one of them is supported for input at a time. When autoDocTypes is provided, ZOLOZ will automatically classify the document uploaded. The passport auto-classification feature is supported, but it is only available in the Native SDK. 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, the checkresult API will return NO_REQUIRED_ID. The value of items in autoDocTypes must be a valid docType. Supported document types, see Document types supported and OCR results returned.
autoDocCategory	List<String>	-	null	Optional. 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`.
autoDocPages	Map<String, String>	-	null	Optional. Specify document pages for recognition after automatic classification. After automatic classification, specify the pages for document recognition. This parameter is required only when passing `autoDocTypes`. Key: The document type passed in `autoDocTypes`. Value: Specify the pages to scan as follows: 1: Scan the first page 1,2: Scan the first and second pages
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.
sceneCode	String	64	null	Optional. Specifies the business scene for data analysis purposes. 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 purposes; for example, registration, withdraw, topUp, transfer, changePassword.
serviceLevel	String	32	REALID0001	Optional. Specifies the service level for spoofing checks and face liveness detection.These parameters are pre-configured based on different integration modes, including detection levels, facial actions, and frame collection settings. If you need to customize these configurations, please use the productConfig-related fields. The supported values for serviceLevel can be found in the serviceLevel.
operationMode	String	32	STANDARD	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_VC_CLOSED`: You can use this operation mode to disable Velocity feature. `STANDARD_IDN_CLOSED`: You can use this operation mode to disable IDN feature. `STANDARD_VC_IDN_CLOSED`: You can use this operation mode to disable Velocity feature and IDN feature. Note: When the value is set to `STANDARD_VC_CLOSED`, `STANDARD_IDN_CLOSED` or `STANDARD_VC_IDN_CLOSED`, other algorithm capabilities are the same as `STANDARD`. 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 checkresult \|API Reference. 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.
pages	String	32	all pages of the specified document	Optional. Specifies the document page numbers to scan and upload, separated by commas. E.g. "1" (scan the first page), "1,2" (scan the first and second page) Supported number of pages for documents can be found in the Document types supported and OCR results returned. Note: If this field is not provided, it defaults to all pages supported by the corresponding document type. When `autoDocTypes` or `autoDocCategory` is Passed In, the `pages` Parameter Must Be Empty; Otherwise, it Will Return INVALID_ARGUMENT.
pageConfig	PageConfig		null	Optional. Specifies the configuration settings for the embedded H5 page. For more information, see pageConfig.
h5ModeConfig	H5ModeConfig		null	Optional. Specifies the configuration settings for H5 Real ID flow. Set this field when the H5 mode is specified with the flowType filed as `H5_REALIDLITE_KYC`. For more information, see h5ModeConfig.
productConfig	ProductConfig		null	Optional. Specifies finer controls for the Real ID product. For more information, see productConfig.

ServiceLevel

ServiceLevel	Supported SDK Modes	Document Collection Method	Spoofing Checks Level	Facial Movement	Additional Collected Images
REALID0001	Native SDK and Web SDK	Manual Capture	Standard	Blink	None
REALID0002	Native SDK	Automatic Capture	Advanced	Blink	None
REALID0002	Web SDK	Manual Capture	Standard	Blink	HKID can capture additional multi-angle frames
REALID0003	Native SDK	Automatic Capture	Advanced	Randomly select two from the following list: blink, open mouth, head up, head down, head turn left, head turn right	None
REALID0003	Web SDK	Manual Capture	Standard		HKID can capture additional multi-angle frames
REALID0004	Native SDK	Automatic Capture without Document Alignment Frame	Standard	Blink	None
REALID0009	Native SDK	Automatic Capture	Advanced	Blink	Closed-eye frame
REALID0011	Web SDK	Manual Capture	Standard	Blink	HKID can capture additional multi-angle frames Closed-eye frame
REALID0012	Web SDK	Automatic Capture	Advanced	Blink	None

Response parameters

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 identity proofing process. This ID will be used as an input parameter for the Real ID 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 the SDK connection and behavior. The value of this field is specified only when the result.resultStatus field is `"S"`.

Result

Result process logic

For different request results, different actions will be performed. See the following for details:

If the value of the result.resultStatus is S , the ZOLOZ Real ID initialize API is invoked successfully and a unique transaction ID is returned.
If the value of the result.resultStatus is F , the invocation of the ZOLOZ Real ID initialize API fails. Check the error code and its message for more information on the possible reasons why.

Common error codes

For the full list of common error codes, see the Common error codes section in the Error handling topic.

API-specific error codes

The following table shows the possible error codes that are specific for the Real ID initialize API.

resultCode	resultStatus	Description
SUCCESS	S	The API call is successful.
HIGH_RISK	F	High risks are detected. The user account is strategically cooled down by the risk engine.
ACCOUNT_SERVICE_SUSPEND	F	The user account is blacklisted by the risk engine.
DEVICE_NOT_SUPPORT	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.
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 that is returned and the related log.

Sample

Request sample

For different integration modes, the request structures are slightly different. When the identity proofing process is initiated in the H5 mode, additionally, an object called h5ModeConfig must be specified. Refer to the following two request samples for more detailed information.

Native RealId Request Sample

The following sample shows what a request looks like if the identity proofing process is initiated in the App SDK mode.

copy
{
  "bizId": "2017839040588699",
  "flowType": "REALIDLITE_KYC",
  "userId": "123456abcd",
  "autoDocTypes":["00630000032","00630000004"],
  "autoDocPages":{
  "00630000032": "1",
  "00630000004": "1,2"
  },
  "pageConfig":{
     "urlFaceGuide":"http://xxxxxx.html"
  },
  "serviceLevel": "REALID0001",
  "operationMode": "STANDARD",
  "productConfig": {
    "deeperMode":"STANDARD",
    "cropDocImage": "Y",
    "landmarkCheck": [
      {"name":"kadPengenalan"},
      {"name":"mykadLogo"},
      {"name":"flagLogo"},
      {"name":"mscLogo"},
      {"name":"ghostFace"},
      {"name":"hibiscusLogo"},
      {"name":"coatOfArm"},
      {"name":"twinTower"}
    ],
    "hologramCheck": [
      {"name":"hologram"}
    ],
    "pageInfoCheck": [
      {"name":"id"},
      {"name":"symbol"},
      {"name":"name"}
    ],
    "preciseTamperCheck": "Y",
    "allowExpiredDocument": "Y",
    "faceAttributeCheck": {
      "occlusionCheck": {
        "details": [
          "eyesOcclusion",
          "noseOcclusion",
          "mouthOcclusion",
          "foreheadOcclusion",
          "chinOcclusion",
          "cheekOcclusion"
        ],
        "detectOpen": "Y",
        "needRetry": "Y"
      },
      "maskCheck": {
        "detectOpen": "Y",
        "needRetry": "N"
      },
      "glassesCheck": {
        "detectOpen": "Y",
        "needRetry": "N"
      },
      "hatCheck": {
        "detectOpen": "Y",
        "needRetry": "N"
      }
    },
    "consistencyCheck": [
      {
        "type": "commonConsistencyCheck"
      },
      {
        "details": [
          "NAME",
          "SEX"
        ],
        "type": "mrzVisualConsistencyCheck"
      },
      {
        "valueRange": [
          "CHN",
          "PHL"
        ],
        "type": "passportCountryCheck"
      }
    ],
    "advancedIdnRiskDetection": {
        "riskTypes": [
            "IDFAKE",
            "DUPLICATE",
            "BATCH_REGISTER",
            "DEEPFAKE"
            ],
        "timeWindow": {
            "endTime": 1724377636300,
            "startTime": 1724222116300
            }
        },
    "advancedIdnThreshold": "3",
    "checkAdvancedIdn": "Y",
    "checkBlacklist": "Y"
  },
  "metaInfo": "{
    \"deviceType\": \"deviceType\",
    \"appVersion\": \"1.0\",
    \"osVersion\": \"7.1.1\",
    \"appName\": \"com.company.wallet\",
    \"bioMetaInfo\": \"3.37.0:262144,0\",
    \"apdidToken\": \"mock-apdidToken\",
    \"deviceModel\": \"MI 6\",
    \"zimVer\": \"2.0.0\"
  }"
}

H5 RealId Request Sample

For different integration modes, the request structures are slightly different. When the identity proofing process is initiated in the H5 mode, additionally, an object called h5ModeConfig must be specified. Refer to the following two request samples for more detailed information.

copy
{
  "bizId": "2017839040588699",
  "flowType": "H5_REALIDLITE_KYC",
  "userId": "123456abcd",
  "autoDocTypes"::["00630000032","00630000004"],
  "autoDocPages":{
  "00630000032": "1",
  "00630000004": "1,2"
  },
  "pageConfig":{
     "urlFaceGuide":"http://xxxxxx.html"
  },
  "serviceLevel": "REALID0001",
  "operationMode": "STANDARD",
  "productConfig": {
    "deeperMode":"STANDARD",
    "cropDocImage": "Y",
    "landmarkCheck": [
      {"name":"kadPengenalan"},
      {"name":"mykadLogo"},
      {"name":"flagLogo"},
      {"name":"mscLogo"},
      {"name":"ghostFace"},
      {"name":"hibiscusLogo"},
      {"name":"coatOfArm"},
      {"name":"twinTower"}
    ],
    "hologramCheck": [
      {"name":"hologram"}
    ],
    "pageInfoCheck": [
      {"name":"id"},
      {"name":"symbol"},
      {"name":"name"}
    ],
    "preciseTamperCheck": "Y",
    "allowExpiredDocument": "Y",
    "faceAttributeCheck": {
      "occlusionCheck": {
        "details": [
          "eyesOcclusion",
          "noseOcclusion",
          "mouthOcclusion",
          "foreheadOcclusion",
          "chinOcclusion",
          "cheekOcclusion"
        ],
        "detectOpen": "Y",
        "needRetry": "Y"
      },
      "maskCheck": {
        "detectOpen": "Y",
        "needRetry": "N"
      },
      "glassesCheck": {
        "detectOpen": "Y",
        "needRetry": "N"
      },
      "hatCheck": {
        "detectOpen": "Y",
        "needRetry": "N"
      }
    },
    "consistencyCheck": [
      {
        "type": "commonConsistencyCheck"
      },
      {
        "details": [
          "NAME",
          "SEX"
        ],
        "type": "mrzVisualConsistencyCheck"
      },
      {
        "valueRange": [
          "CHN",
          "PHL"
        ],
        "type": "passportCountryCheck"
      }
    ],
    "advancedIdnRiskDetection": {
        "riskTypes": [
            "IDFAKE",
            "DUPLICATE",
            "BATCH_REGISTER",
            "DEEPFAKE"
            ],
        "timeWindow": {
            "endTime": 1724377636300,
            "startTime": 1724222116300
            }
        },
     "advancedIdnThreshold": "3",
     "checkAdvancedIdn": "Y",
     "checkBlacklist": "Y"
  },
  "metaInfo": "MOB_H5",
  "h5ModeConfig":{
    "completeCallbackUrl":"http://xxx.html",
    "interruptCallbackUrl":"http://xxx.html",
    "allowDegradation":"Y",
    "docFrontPageGuideUrl":"http://xxx.html",
    "docBackPageGuideUrl":"http://xxx.html",
    "facePageGuideUrl":"http://xxx.html",
    "uiCfg": "{\"titlebarbgcolor\":\"#ffffff\",\"titlebartextcolor\":\"#000000\",\"buttoncolor\":\"#3696fd\",\"isDesktop\":\"Y\"}"
    "enableUpload": "Y"
  }
}

Response Sample

The following sample shows what a response returned from the ZOLOZ server looks like.

copy
{
   "result": {
        "resultStatus": "S",
        "resultCode": "SUCCESS",
        "resultMessage": "Success"
    },
  "transactionId":"G000000005FID20200304000000000001570702", 
  "clientCfg": "……"   
}

More information

pageConfig

The following table shows the fields that can be specified in the pageConfig data model.

Field name	Data type	Max length	Description
urlFaceGuide	String	256	Optional. Specifies the URL to the face guide page, which is an H5 prompt page that can be customized to guide users during face scanning. For example, http://xxxxxx.html.

h5ModeConfig

The following table shows the fields that can be specified in the h5ModeConfig data model.

Field name	Data type	Max length	Default Value	Description
state	String	128	the value of `transactionId`	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 instead.
completeCallbackUrl	String	128	-	Required. Specifies the callback URL where the browser is redirected 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.
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).
isIframe	String	1	N	Optional. If the Web Page needs to be open in Iframe, this parameter should be set as `Y`. The following values are supported: `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. When isDesktop is Y, serviceLevel only supports REALID0001, 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\",\"isDesktop\":\"#3696fd\"}"
enableUpload	String	1	N	Optional. If it supports to upload document images from desktop. Default value: `N` The following values are supported: `Y`: Supports file upload from the desktop to obtain document images. `N`: Does not support file upload from the desktop to obtain document images. Note: `enableUpload` should be used together with `isDesktop`. If `enableUpload` is `Y`, `isDesktop` should be `Y`. Otherwise, `INVALID_ARGUMENT` will be returned.
allowDegradation	String	1	N	Optional. If degraded mode is allowed, this parameter should be set to `Y`. The following values are supported: `Y`: Degraded mode is allowed. `N`: Degraded mode is not allowed. Notes: When this parameter is set to `Y`, the user can choose to enter degraded mode if Zoloz detects that the user's browser does not support Web SDK. Upon confirmation of entering degraded mode, Zoloz will initiate the native camera system for taking photos. Degraded mode may pose a higher risk. The highest eKYC result of transactions from this source is Pending, which requires a second check.
docFrontPageGuideUrl	String	128	null	Optional. Specifies the URL of the first page of the document guide page in downgrade mode. This is an H5 prompt page that can be customized to guide users in collecting the first page of the document. If this parameter is not provided, the default page will be displayed.
docBackPageGuideUrl	String	128	null	Optional. Specifies the URL of the second page of the document guide page in downgrade mode. This is an H5 prompt page that can be customized to guide users in collecting the second page of the document. If this parameter is not provided, the default page will be displayed.
facePageGuideUrl	String	128	null	Optional. Specifies the URL of the face guide page in downgrade mode. This is an H5 prompt page that can be customized to guide users in collecting selfies. If this parameter is not provided, the default page will be displayed.

productConfig

The following table shows the fields that can be specified in the productConfig data model.

Field name	Data type	Max length	Default Value	Description	Notes
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
cropFaceImage	String	1	N	Optional. Specifies whether to crop the face area of the captured FACE image. Valid values include: `Y`: Return an additional face image cropped from the original captured face image `N`: Default value. Do not crop
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
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.
pageInfoCheck	Array		null	Optional. Specifies 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.
preciseTamperCheck	String	1	N	Deprecated field, will no longer be maintained. To ensure API compatibility, this field will be retained. Optional. Specify whether to perform a precise tamper check. Precise tamper checks are only applicable for selected documents. The following values are supported: Y: Yes N: Do not perform a precise tamper check
allowExpiredDocument	String		Different document types have different default values, which are set as follows: `Y`: For all documents except Passport (docType=00000001003) `N`: For Passport (docType=00000001003)	Optional. Specifies whether expired documents are allowed. The following values are supported: `Y`: Allow expired documents. `N`: Pause Real ID 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.
docUiType	String	20	Native SDK: 2 Web SDK: 1	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. 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.	The following 10 parameters have a higher priority than serviceLevel and operationMode. If any of these 10 parameters are passed, the default values of the other parameters will take effect. In this case, even if the values of serviceLevel and operationMode are passed, they will not take effect. docUiType spoofMode livenessMode antiInjectionMode deeperMode actionCheckItems actionRandom actionFrame riskMode idnThreshold
spoofMode	String	10	STANDARD	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`: A standard recommended level is applied. `LOOSE`: Reserved value, not currently supported for use. `STRICT`: Reserved value, not currently supported for use.
livenessMode	String	10	STANDARD	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`: 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	CLOSED	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`: 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.
deeperMode	String	10	CLOSED	Optional. Specifies the Deeper level for AIGC attack detection. For a detailed description of the Deeper detection function, refer to the What is the Deeper. The following values are supported: `CLOSED`: All capability about Deeper are not applied, e.g. AIGC detection algorithms, terminal risk detection, etc. If the business scenario does not require AIGC attack detection, you do not need to enable it. `STANDARD`: A standard recommended level is applied. `LOOSE`: A relatively looser level is applied. You can use this detection mode in low-risk scenarios. `STRICT`: A relatively stricter level is applied. You can use this detection mode in high-risk scenarios. Note: Please make sure to purchase the Deeper product before enabling this feature.
actionCheckItems	List<String>		FACEBLINK	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`: 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	N	Optional. Specifies whether user actions specified in `actionCheckItems` are in random order to be detected. Valid values include: `Y`: Random `N`: Not random, action detection is performed following the order in actionCheckItems.
actionFrame	List<String>		null	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	String	10	STANDARD	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 about risk detection 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`: A standard recommended level is applied. `LOOSE`: Reserved value, not currently supported for use. `STRICT`: Reserved value, not currently supported for use.
idnThreshold	Integer		3	This parameter has been deprecated and will no longer be maintained in the future. In order to ensure API compatibility, this parameter will continue to be retained. Optional. 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.
faceAttributeCheck	faceAttributeCheck		null	Optional. This parameter is used to Specifies whether to detect face attributes and control whether to retry when face attributes are detected.	The `faceAttributeCheck` parameters take precedence over `livenessMode`. For example, if `occlusionCheck.detectOpen` is set to `N`, even `livenessMode` is set to `STRICT`, the face occlusion check is disabled. For details, please refer to the faceAttributeCheck.
consistencyCheck	List<ConsistencyCheckItem>	-	null	Optional. Specifies 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.
checkAdvancedIdn	String	-	N	Optional. Specifies whether to enable IDN risk check. Values: `Y`: Enable. `N`: Disable. Note: You need to purchase IDN before you can enable this function.
advancedIdnRiskDetection	RiskDetection	-	RiskDetection	Optional. Risk detection. For more details, please see RiskDetection. Note: This parameter takes effect only when `checkAdvancedIdn` is set to `Y`.
advancedIdnThreshold	String	-	3	Optional. Specifies the threshold for IDN risk checks, with a range of 1 to 100. Transactions associated with risky historical transactions exceeding the specified threshold will be blocked. The same `itemId` will only be counted once. Note: This parameter takes effect only when `checkAdvancedIdn` is set to `Y`.
checkBlacklist	String	1	N	Optional. Whether to enable blacklist risk check. Values: `Y`: Enable. `N`: Disable. Note: You need to purchase the blacklist capability before enabling this feature.

ConsistencyCheckItem data structure

commonConsistencyCheck

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

mrzVisualConsistencyCheck

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

passportCountryCheck

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
valueRange	List<String>	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 (both MRZ and VIZ) / 00000001006 / COUNTRY_CODE

faceAttributeCheck

Field name	Data type	Max length	Default Value	Description
occlusionCheck	faceAttributeDetails		null	Optional. Specifies whether to detect face occlusion attributes. For details, please refer to the faceAttributeDetails.
maskCheck	faceAttributeDetails		null	Optional. Specifies whether to detect mask attributes. For details, please refer to the faceAttributeDetails.
glassesCheck	faceAttributeDetails		null	Optional. Specifies whether to detect glasses attributes. For details, please refer to the faceAttributeDetails.
hatCheck	faceAttributeDetails		null	Optional. Specifies whether to detect hat attributes. For details, please refer to the faceAttributeDetails.

faceAttributeDetails

Field name	Data type	Max length	Default Value	Description
detectOpen	String		null	Specifies whether to detect face attributes and return its result in checkresult API. `Y`: open the face attribute detection `N`: close the face attribute detection
needRetry	String		null	Specifies whether to retry when the specified attribute is detected. `Y`: Require retry when the specified attribute is detected. `N`: No need for retry when the specified attribute is detected. Note: When `needRetry` is `Y`, `detectOpen` must be set to`Y`.
details	List<String>		null	Specifies whether to return additional detailed information of face attributes. Currently only support occlusionCheck. Available options as follows: `eyesOcclusion`: return eyes occlusion result `noseOcclusion`: return nose occlusion result `mouthOcclusion`: return mouth occlusion result `foreheadOcclusion`: return forehead occlusion result `chinOcclusion`: return chin occlusion result `cheekOcclusion`: return cheek occlusion result Notes: When `details` parameter is not empty, `detectOpen` must be set to `Y`. When `details` parameter is provided, overall and particular attribute results will be returned in checkresult API.

RiskDetection

Field name

Data type

Max length

Default Value

Description

riskTypes

List<String>

["IDFAKE","DUPLICATE"]

Optional. Specifies the type of risk to be queried. The following four major risk types are supported, and the system will automatically query the sub-risks they contain. For more details, see IDN Risk introduction.

IDFAKE: Impersonated identity.
DUPLICATE: Duplicate authentication.
BATCH_REGISTER: Batch register.
DEEPFAKE：Deepfake face

timeWindow

TimeWindow

Optional. The risk query time window can support up to 180 days of data, with the default being the most recent 30 days. For more details, see TimeWindow.

Note: The system limits the data volume for a single scan to 500,000 records. If the data volume within the query time window exceeds 500,000 records, the system will dynamically adjust the time window you set.

TimeWindow

Field name	Data type	Max length	Default Value	Description
startTime	Long	-	Current Time	Optional. Risk query start time, using a 13-digit timestamp.
endTime	Long	-	30 Days Ago	Optional. Risk query end time, using a 13-digit timestamp.

Change log

Date	Change log
Sep 20，2024	The following two parameters are added: passportCountryCheck is added in consistencyCheck of productConfig. checkBlacklist is added in productConfig.
August 1，2024	Deeper related interface information changes
28 March, 2024	A new parameter, faceAttributeCheck, is added in productConfig.
22 November, 2023	Added new fields for the productConfig parameter.
22 May, 2022	A new parameter, productConfig, is added in the request.
8 September，2020	Two more types of identity documents are supported: Malaysia MyKad and Macau identity card. A new parameter, h5ModeConfig, is added in the request.
9 June, 2020	A new parameter, pageConfig, is added in the request.
27 December, 2019	The parameter productLevel is renamed to serviceLevel, and the related description is updated.
20 December, 2019	The following two request parameters are added: productLevel operationMode
06 December, 2019	Released.