checkresult
POST/api/v1/zoloz/realid/checkresult
The ZOLOZ Real ID checkresult API is used to request a result about the identity proofing process running status and other corresponding results, which include basic and detailed document verification results, face verification results, risk control results and so on. This API is idempotent.
structure
Request parameters
Field name | Data type | Max Length | Description |
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. |
transactionId | String | 64 | Required. The unique transaction ID that is returned in the response of the initialize API. |
isReturnImage | String | 1 | Optional. A flag that specifies whether the image data needs to be returned in the response. The following values are supported:
By default, the value of |
extraImageControlList | List<String> | (Optional) Specify whether to return extra document images if isReturnImage is "Y". Valid values include:
Please note that the extra images could be returned are subject to whether these images have been captured, which is controlled by both integration mode and the value of serviceLevel set in initialize API. For example, if the integration mode is Native App SDK , and serviceLevel is REALID0002, then DOC_FRONT_FLASH will be captured and could be returned. | |
returnFiveCategorySpoofResult | String | 1 | (Optional) Specify whether to return document spoofing check results in 5 categories. Valid values include:
|
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. | |
ekycResult | String | Optional. Specifies the running status of the whole identity proofing process. This field is only available when the value of the result.resultSatus filed is
|
extBasicInfo | ExtBasicInfo | Optional. Basic real-name information. This field is only available when the value of the result.resultStatus field is set to |
extFaceInfo | ExtFaceInfo | Detailed eKYC application face information. Only available when result.resultStatus is Optional. Detailed information about face verification. This field is only available when the value of the result.resultStatus field is set to |
extIdInfo | ExtIdInfo | Optional. Detailed information about document verification. This field is only available when the value of the result.resultStatus field is set to |
extRiskInfo | ExtRiskInfo | Optional. Detailed information about risk control. This field is only available when the value of the result.resultStatus field is set to |
Result
Result process logic
For different request results, different actions are to be performed. See the following for details:
- If the value of the result.resultStatus is
S
, the ZOLOZ Real ID checkresult API is invoked successfully, and results about document verification, face verification, and risk control processing are returned. - If the value of the result.resultStatus is
F
, the invocation of the ZOLOZ Real ID checkresult API fails. Check the error code and message for more information about the possible reasons. Error codes.
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 checkresult API.
resultCode | resultSatus | Description |
SUCCESS | S | The API call is successful. |
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 or the related log. |
Sample
Request Sample
The following sample shows what a request that the merchant server sends looks like.
{
"bizId": "2017839040588699",
"transactionId": "G000000005FID20200304000000000001570702",
"isReturnImage": "Y",
"extraImageControlList": [
"FACE_EYE_CLOSE",
"DOC_FRONT_ANGLE"
],
"returnFiveCategorySpoofResult": "Y"
}
Response Sample
The following sample shows what a response that the ZOLOZ server returns looks like.
{
"result": {
"resultCode": "SUCCESS",
"resultMessage": "Success",
"resultStatus": "S"
},
"ekycResult": "Pending",
"extBasicInfo": {
"certType": "08530000001",
"certNo": "A12345678",
"certName": "xxxxxx"
},
"extFaceInfo": {
"ekycResultFace": "Success",
"faceScore": 88.31415926535897,
"faceImg": "/9j/4AA..[omitted]..PxA=",
"extraImages": {
"FACE_EYE_CLOSE": "/9j/4AA..[omitted]..PxA="
},
"faceQuality": 97.61517973846627,
"faceLivenessResult": "Success"
},
"extIdInfo": {
"ekycResultDoc": "Pending",
"docEdition": 1,
"frontPageImg": "/9j/4AA..[omitted]..PxA=",
"backPageImg": "/9j/4AA..[omitted]..PxA=",
"extraImages": {
"DOC_FRONT_ANGLE": "/9j/4AA..[omitted]..PxA=",
"CROPPED_FRONT": "/9j/4AA..[omitted]..PxA=",
"CROPPED_BACK": "/9j/4AA..[omitted]..PxA="
},
"ocrResult": {
...
},
"spoofResult": {
"TAMPER_CHECK": "Y",
"MATERIAL_CHECK": "Y",
"SCREEN_RECAPTURE_CHECK": "Y",
"INFORMATION_CHECK": "Y",
"SECURITY_FEATURE_CHECK":,"Y"
},
"extraSpoofResultDetails": [
{
"name": "landmarkCheck",
"result": "Y",
"spoofType": "SECURITY_FEATURE_CHECK",
"components": [
{
"name": "kadPengenalan",
"subResult": "Y"
},
{
"name": "mykadLogo",
"subResult": "Y"
},
{
"name": "flagLogo",
"subResult": "Y"
},
{
"name": "mscLogo",
"subResult": "Y"
},
{
"name": "ghostFace",
"subResult": "Y"
},
{
"name": "hibiscusLogo",
"subResult": "Y"
},
{
"name": "coatOfArm",
"subResult": "Y"
},
{
"name": "twinTower",
"subResult": "Y"
}
]
},
{
"name": "hologramCheck",
"result": "Y",
"spoofType": "SECURITY_FEATURE_CHECK",
"components": [
{
"name": "hologram",
"subResult": "Y"
}
]
},
{
"name": "pageInfoCheck",
"result": "Y",
"spoofType": "INFORMATION_CHECK",
"components": [
{
"name": "id",
"subResult": "Y"
},
{
"name": "symbol",
"subResult": "Y"
},
{
"name": "name",
"subResult": "Y"
}
]
}
],
"securityFeaturesResult": {
"LASER_IMAGE_1_SCORE":95,
"LASER_IMAGE_1_THRESHOLD":90,
"LASER_IMAGE_1_PASSED":"True",
"HOLOGRAM_SCORE":95,
"HOLOGRAM_THRESHOLD":90,
"HOLOGRAM_PASSED":"True",
"STEREO_LASER_PORTRAIT_SCORE":95,
"STEREO_LASER_PORTRAIT_THRESHOLD":90,
"STEREO_LASER_PORTRAIT_PASSED":"True",
"LASER_IMAGE_2_SCORE":95,
"LASER_IMAGE_2_THRESHOLD":90,
"LASER_IMAGE_2_PASSED":"True",
"OVERALL_SCORE":95,
"OVERALL_THRESHOLD":90,
"OVERALL_PASSED":"True"
},
"docErrorDetails": "BLUR"
},
"extRiskInfo": {
"ekycResultRisk": "Pending",
"strategyPassResult": "ID_NETWORK_HIGH_RISK",
"idNetworkDetails": "..."
}
}
More information
ExtBasicInfo
The following table shows the fields that can be specified in the ExtBasicInfo data model.
Field name | Data type | Description |
certType | String | ID type. Specifies the type of the identity document. Required if the document verification process runs successfully. |
certNo | String | ID number. Specifies the ID number that is recognized from the identity document. Required if the document verification process runs successfully. |
certName | String | ID name. Specifies the name that is recognized from the identity document. Required if the document verification process runs successfully. |
ExtFaceInfo
The following table shows the fields that can be specified in the ExtFaceInfo data model.
Field name | Data type | Description |
ekycResultFace | String | Specifies the result of the face verification process. Possible values and their meanings are as below:
Required if the face verification process runs successfully. |
faceScore | Double | Specifies the score that indicates a result of comparing the live face (selfie) against the one that is recognized from the identity document. Required if the face verification process runs successfully. The value of this field is in the range of 0-100. |
faceImg | String | The face selfie image, which is encoded in base64. This field is specified only when the value of the isReturnImage field in the request is set to |
extraImages | Map<String,String> | Contain the extra face images specified in request.extraImageControlList. Key is the value specified in request.extraImageControlList. Value is the image content encoded in base64. If the requested image is not found, the value will be "". |
faceQuality | Double | Specifies the quality score of the face selfie image. Required if the face verification process runs successfully. The value of this field is in the range of 0-100. |
faceLivenessResult | String | Specifies whether the face selfie image is detected as a fake face attack by using the face liveness check algorithm. If the image is not a fake face attack, the value of |
ExtIdInfo
The following table shows the fields that can be specified in the ExtIdInfo data model.
Field name | Data type | Description |
ekycResultDoc | String | Specifies the result of the document verification process. Possible values and their meanings are as below:
Required if the document verification process runs successfully. |
docEdition | Integer | Specifies the edition of the identity document. For example, for the current HKID, the value of this field is returned as Required if the document verification process runs successfully. |
frontPageImg | String | The frontside image of the identity document. The image must be encoded in base64. This field is specified only when the value of the isReturnImage field in the request is set to |
backPageImg | String | The backside image of the identity document (if any). The image must be encoded in base64. This field is specified only when the value of the isReturnImage field in the request is set to |
extraImages | Map<String,String> | Contain extra doc images specified in request.extraImageControlList and request.cropImage parameter. Key is the value specified in request.extraImageControlList if request.extraImageControlList is not blank. Possible Key values if request.cropImage is not blank:
Value is the image content encoded in base64. If the requested image is not found, the value will be "". |
ocrResult | Map | The OCR result, which contains information about the identity. Required if the document verification process runs successfully. Depending on the type of the identity document, different sets of identity information are recognized. For more information, see Document types supported and OCR results returned. |
spoofResult | Map | Optional. The spoofing check result, which contains information about the check results in terms of tampering, authenticity of the document material, and screen recapture. For more information, see spoofResult. |
securityFeaturesResult | Map | Optional. Specifies the detection result on the security features of an identity document, for example, the laser image on the identity document. Depending on the identity document type, different security features of the identity document are checked. For more information, see securityFeaturesResult. |
docErrorDetails | String | Optional. Specifies the error details of the document verification process. Possible values and their meanings are as below:
|
ExtRiskInfo
The following table shows the fields that can be specified in the ExtRiskInfo data model.
Field name | Data type | Description |
ekycResultRisk | String | Specifies the result of the risk control process. Possible values and their meanings are as below:
|
strategyPassResult | String | Specifies the result of risk check. Required if the risk control process runs successfully. Possible values and their meanings are as below:
|
idNetworkDetails | String | Optional. Specifies the detailed information about the ID network output. This field is specified only when the strategyPassResult field returns as |
otherRiskReasonDetails | String | Optional. Specifies the detailed outputs of risk engines other than ID Network. For example, in the case of blacklist hits, the structure of this field will be like: { "BLACKLIST_HIGH_RISK": { "CERT": [ {"listId":"xx","transactionId":"xx","itemId":xx,"similarScore":xx} ], "FACE":[ {"listId":"xx","transactionId":"xx","itemId":"xx","similarScore":xx} ] } } |
spoofResult
The following table shows the detailed information that is included in a spoofing check result.
Field name | Data type | Description |
TAMPER_CHECK | String | Required. Specifies whether the input identity document passes the tampering check. If the identity document does not pass the check, which means it is detected as tampered, the value of |
MATERIAL_CHECK | String | Required. Specifies whether the material of the identity document passes the authenticity check. If the material of the identity document does not pass the check, for example, detected in black and white, the value of |
SCREEN_RECAPTURE_CHECK | String | Required. Specifies whether the identity document passes the screen recapture check. If the identity document does not pass the check, which means the image uploaded is detected as an image recaptured from a screen, the value of |
INFORMATION_CHECK | String | (Optional) indicate whether the identity document passed information check. Returned only if the "returnFiveCategorySpoofResult" parameter is set to "Y". Possible values include: Y: passed information check. N: failed information check.e.g. the ID number digit does not match encoding rules. |
SECURITY_FEATURE_CHECK | String | (Optional) Indicate whether the identity passed security feature check. Returned only if the "returnFiveCategorySpoofResult" parameter is set to "Y". Possible values include: Y: passed security feature check. N: failed security feature check. |
extraSpoofResultDetails
The following table shows the data structure of an element of the spoofResultDetails array.
Field name | Data type | Description |
name | String | Required. Indicate the name of the detailed document spoof check. For example, "landmarkCheckResult", "hologramCheckResult" |
result | String | Required. Indicate the result of the detailed document spoof check. Possible values include:
|
spoofType | String | Required. Indicate the detailed document spoofing check category. Possible values include:
|
components | Array | Required. Contain check result of each components. It will always be returned. If there is only one component check specified, the array will return one element. |
components.name | String | Required. Indicate the name of the component. To understand possible values, please refer to the spoofing check details document for more information. |
components.subResult | String | Required. Indicates the result of the component.
|
securityFeaturesResult
The following table shows the security features that are detected for different identity documents, and the fields that are returned in the securityFeaturesResult data model. For each security feature, a check result is returned, which includes a score, a threshold value and a flag that indicates whether the corresponding check is passed. In addition, an overall check result is also returned.
Currently the security feature detection only supports HKIDs (both the current and new versions).
Identity document | docType | Security feature example | Fields and value examples |
Current HKID (Hong Kong Identity Card) | 08520000001 | Figure 1. A sample image of the current HKID Note: The sample image comes from https://www.smartid.gov.hk/en/Development-of-Hong-Kong-Identity-Cards/index.html. | As Figure 1 shows, for the current HKID, security features are detected in terms of optical variable ink, multiple laser image and Kineprint. The following list shows the fields and value examples for each security feature and overall check result.
Overall:
|
New HKID | 08520000002 | Figure 2. A sample image of the new HKID Note: The sample image comes from https://www.smartid.gov.hk/en/Security-Features-of-New-Smart-Identity-Card/index.html | As Figure 2 shows, for the new HKID, security features include laser image1, hologram, stereo laser(SLI) portrait, and laser image2. The following list shows the fields and value examples for each security feature and overall check result.
Overall:
|
Version
Date | Change log |
22 May, 2022 | New input parameters of extraImageControlList, returnFiveCategorySpoofResult and new output parameters of extraImages, extraSpoofResultDetails are added. |
23 October, 2020 | OCR result keys for China identity card are added. |
8 September, 2020 | Two more types of identity documents are supported: Malaysia MyKad and Macau identity card. |
30 July, 2020 |
|
21 May, 2020 |
|
27 December, 2019 | The letter case convention of the parameter name is updated. |
06 December, 2019 | Released. |