initialize
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
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 |
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 |
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 |
|
REALID0012 | Web SDK | Automatic Capture | Advanced | Blink | None |
Response parameters
Field name | Data type | Description |
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: when an error occurs during the process, for example, an invalid argument, no transaction ID will be returned. |
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 |
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.
{
"bizId": "2017839040588699",
"flowType": "REALIDLITE_KYC",
"userId": "123456abcd",
"autoDocTypes":["08520000001","08520000002"],
"pageConfig":{
"urlFaceGuide":"http://url-to-face-guide-page.htm"
},
"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.
{
"bizId": "2017839040588699",
"flowType": "H5_REALIDLITE_KYC",
"userId": "123456abcd",
"autoDocTypes":["08520000001","08520000002"],
"pageConfig":{
"urlFaceGuide":"http://url-to-face-guide-page.htm"
},
"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"
}
}
Response Sample
The following sample shows what a response returned from the ZOLOZ server looks like.
{
"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://url-to-face-guide-page.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 | 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
|
uiCfg | String | 256 | null | Optional. Custom UI configurations in the JSON string format. Only supports For example: |
allowDegradation | String | 1 | N | Optional. If degraded mode is allowed, this parameter should be set to
Notes:
|
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:
| |
cropFaceImage | String | 1 | N | Optional. Specifies whether to crop the face area of the captured FACE image. Valid values include:
| |
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. | ||
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:
| |
allowExpiredDocument | String | Different document types have different default values, which are set as follows:
| Optional. Specifies whether expired documents are allowed. The following values are supported:
Note: Invalid values will fall back to the default option and pause the Real ID process when an expired document is detected. | ||
docUiType | String | 20 |
| Optional. This parameter refers to methods for taking ID photos. The values are as follows:
| 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.
|
spoofMode | String | 10 | STANDARD | Optional. This parameter refers to document anti-spoofing levels, defined as follows:
| |
livenessMode | String | 10 | STANDARD | Optional. Specifies the liveness level for face liveness detection check. The following values are supported:
| |
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:
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:
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:
| ||
actionRandom | String | 1 | N | Optional. Specifies whether user actions specified in
| |
actionFrame | List<String> | null | Optional. This parameter refers to capturing other frame pictures, defined as follows:
| ||
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:
| |
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 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 For example, if | |
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:
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 | |
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 Note: This parameter takes effect only when | |
checkBlacklist | String | 1 | N | Optional. Whether to enable blacklist risk check. Values:
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
|
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.
| MyVisa / Malaysia / 00600000011 /
|
Passport (both MRZ and VIZ) / CHN, HKG, TWN, MAC, PHL, SGP, MYS/ 00000001006 /
|
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 | |
valueRange | List<String> | should be the same as the default country code. | when type is passportCountryCheck, | for below docTypes,
|
each item should comply with ISO_3166-1_alpha-3 | for below docTypes,
|
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.
| |
needRetry | String | null | Specifies whether to retry when the specified attribute is detected.
Note: When | |
details | List<String> | null | Specifies whether to return additional detailed information of face attributes. Currently only support occlusionCheck. Available options as follows:
Notes:
|
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.
|
timeWindow | 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:
|
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 |
|
9 June, 2020 | A new parameter, pageConfig, is added in the request. |
27 December, 2019 |
|
20 December, 2019 | The following two request parameters are added:
|
06 December, 2019 | Released. |