checkresult

2024-04-02 01:47

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	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.
transactionId	String	64	-	Required. The unique transaction ID that is returned in the response of the initialize API.
isReturnImage	String	1	N	Optional. A flag that specifies whether the image data needs to be returned in the response. The following values are supported: `Y` : The image data needs to be returned in the response. `N` : The image data does not need to be returned in the response.
extraImageControlList	List<String>		[]	Optional. Specify whether to return extra document images if isReturnImage is "Y". The following values are supported: `FACE_EYE_CLOSE`: returns a face image with closed eyes `DOC_FRONT_ANGLE`: return doc front page image captured with multiple angles. `DOC_FRONT_FLASH`: return doc front page image captured with flashlight on. `DOC_BACK_ANGLE`: return doc back page image captured with multiple angles. `DOC_BACK_FLASH`: return doc back page image captured with flashlight on. `CROPPED_FACE`: return an additional face image cropped from the original captured face image. Note: The possibility of additional images being returned is dependent on whether these images have been captured successfully. This is determined by both the integration mode and the serviceLevel value set in the initialize API. For example, if the integration mode selected is Native App SDK and the serviceLevel value is `REALID0002`, then `DOC_FRONT_FLASH` will be captured and may be returned.
returnFiveCategorySpoofResult	String	1	N	Optional. Specify whether to return document spoofing check results in 5 categories. Valid values include: `Y`: document spoofing check result will be returned in 5 categories, including: `TAMPER_CHECK` `MATERIAL_CHECK` `SCREEN_RECAPTURE_CHECK` `INFORMATION_CHECK` `SECURITY_FEATURE_CHECK` `N`: document spoofing check result will be returned in 4 categories, including: `TAMPER_CHECK` `MATERIAL_CHECK` `SCREEN_RECAPTURE_CHECK` `OTHER_CHECK`

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.
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 `S` . Possible values and their meanings are as below: `Success` : the identity proofing process runs successfully. `Pending` : the identity proofing process is pending. `Failure` : the identity proofing process fails, which indicates that at lease one of the document verification, face verification or risk control processing fails. `InProcess` : the identity proofing process is in progress. `VoidCancelled` : the identity proofing process is cancelled. `VoidTimeout` : the identity proofing process is timed out.
extBasicInfo	ExtBasicInfo	Optional. Basic real-name information. This field is only available when the value of the result.resultStatus field is set to `S`. For more information, see ExtBasicInfo.
extFaceInfo	ExtFaceInfo	Detailed eKYC application face information. Only available when result.resultStatus is `S`. Refer to the table below for details. Optional. Detailed information about face verification. This field is only available when the value of the result.resultStatus field is set to `S`. For more information, see ExtFaceInfo.
extIdInfo	ExtIdInfo	Optional. Detailed information about document verification. This field is only available when the value of the result.resultStatus field is set to `S`. For more information, see ExtIDInfo.
extRiskInfo	ExtRiskInfo	Optional. Detailed information about risk control. This field is only available when the value of the result.resultStatus field is set to `S`. For more info, see ExtRiskInfo.

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.

copy
{
    "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.

copy
{
  "result": {
    "resultCode": "SUCCESS",
    "resultMessage": "Success",
    "resultStatus": "S"
  },
  "ekycResult": "Pending",
  "extBasicInfo": {
    "certType": "08530000001",
    "certNo": "A12345678",
    "certName": "xxxxxx"
  },
  "extFaceInfo": {
    "ekycResultFace": "Success",
    "faceScore": 88,
    "faceImg": "/9j/4AA..[omitted]..PxA=",
    "extraImages": {
      "FACE_EYE_CLOSE": "/9j/4AA..[omitted]..PxA="
    },
    "faceQuality": 97.61517973846627,
    "faceLivenessResult": "Success",
    "estimatedAge": 34,
     "faceAttribute": {
      "occlusionMouthResult": "false",
      "occlusionForeheadResult": "false",
      "occlusionResult": "false",
      "occlusionChinResult": "false",
      "occlusionEyesResult": "false",
      "occlusionNoseResult": "false",
      "occlusionCheekResult": "false",
      "maskResult": "false",
      "glassesResult": "true",
      "hatResult": "false"
    }
  },
  "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": "[{\"ekyc_id\":\"\",\"mobile\":\"\",\"reason_code\":[\"SIMILAR_FACE\"],\"type\":\"Fake ID\",\"user_id\":\"idn-z8Cuj\"}]"
  }
  }
}

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: `Success` : The face verification process runs successfully. `Pending` : The face verification process is pending. `Failure` : The face verification process fails. Required if the face verification process runs successfully.
faceScore	Integer	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 `Y` and the face verification process runs successfully.
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 `Success` is returned; otherwise, the value of `Failure` is returned.
estimatedAge	Integer	Specifies estimated age based on the face selfie image. Notes: The age estimation accuracy rate is 95% within a given age error range of 0-10 years. The value of this field is for reference only, which is not used for business judgement by ZOLOZ. If you need to intercept transactions for specific age, please add your own verification logic.
faceAttribute	Map<String,String>	Specifies the result of face attribute detection. For more details, please refer to the faceAttribute. Note: This field is returned only when the faceAttributeCheck parameter is passed in and `detectOpen` is set as `Y` in the initialize API of Real ID.

faceAttribute

Field name	Data type	Description
occlusionMouthResult	String	Specifies mouth occlusion detection result. `true`: Occlusion is present. `false`: No occlusion.
occlusionForeheadResult	String	Specifies forehead occlusion detection result. `true`: Occlusion is present. `false`: No occlusion.
occlusionResult	String	Specifies overall occlusion detection result. `true`: Occlusion is present. `false`: No occlusion.
occlusionChinResult	String	Specifies chin occlusion detection result. `true`: Occlusion is present. `false`: No occlusion.
occlusionEyesResult	String	Specifies eyes occlusion detection result. `true`: Occlusion is present. `false`: No occlusion.
occlusionNoseResult	String	Specifies nose occlusion detection result. `true`: Occlusion is present. `false`: No occlusion.
occlusionCheekResult	String	Specifies cheek occlusion detection result. `true`: Occlusion is present. `false`: No occlusion.
maskResult	String	Specifies mask detection result. `true`: Mask is present. `false`: No mask detected.
glassesResult	String	Specifies glasses detection result. `true`: Glasses is present. `false`: No glasses.
hatResult	String	Specifies hat detection result. `true`: Hat is present. `false`: No hat.

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: `Success` : The document verification process runs successfully. `Pending` : The document verification process is pending. `Failure` : The document verification process process fails. Required if the document verification process runs successfully.
docEdition	Integer	Specifies the edition of the identity document. `1`~`3`: edition of the identity document. For more details, please see Document types supported and OCR results returned. `0`: can not classify the identity document or wrong document type `-1`: unknown error
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 `Y` and the document verification process runs successfully.
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 `Y`, the document verification process runs successfully and it is required to upload the backside image of the identity document.
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: `CROPPED_FRONT`: return the cropped first page of the document `CROPPED_BACK`: return the cropped second page of the document 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.
extraSpoofResultDetails	List<ExtraSpoofResultDetail>	Optional. Extra document spoof detection result details. For more details, see extraSpoofResultDetails.
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: `NO_REQUIRED_ID` : The ID recognized from the uploaded image does not match the specified identity document type. `BLUR` : The uploaded identity document image is blurred. `NO_FACE_DETECTED` : A face that should have been recognized from the specified identity document is not detected from the uploaded image as expected. `NOT_REAL_DOC` : The uploaded identity document image is detected as fake. `EXPOSURE` : The uploaded identity document image is overexposed. `UNKNOWN` : All the other recognition errors.

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 `N` is returned; otherwise, `Y` is returned.
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 `N` is returned; otherwise, `Y` is returned.
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 `N` is returned; otherwise, `Y` is returned.
INFORMATION_CHECK	String	(Optional) Currently only support HKIDs (both the old and new versions). 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) Currently only support HKIDs (both the old and new versions) and MyKad. 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: `Y`: passed check `N`: failed check
spoofType	String	Required. Indicate the detailed document spoofing check category. Possible values include: TAMPER_CHECK MATERIAL_CHECK SCREEN_RECAPTURE_CHECK INFORMATION_CHECK SECURITY_FEATURE_CHECK
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. `Y`: passed check `N`: failed check

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

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.

Optical variable ink

OPTICAL_VARIABLE_INK_SCORE: 70
OPTICAL_VARIABLE_INK_THRESHOLD: 60
OPTICAL_VARIABLE_INK_PASSED: True

Multiple laser image

MULTIPLE_LASER_IMAGE_SCORE: 95
MULTIPLE_LASER_IMAGE_THRESHOLD: 90
MULTIPLE_LASER_IMAGE_PASSED: True
Kineprint

KINEPRINT_SCORE: 85
KINEPRINT_THRESHOLD: 77
KINEPRINT_PASSED: True

Overall:

OVERALL_SCORE: 95
OVERALL_THRESHOLD: 90
OVERALL_PASSED: True

New HKID

08520000002

Figure 2. A sample image of the new HKID

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.

Laser image1

LASER_IMAGE_1_SCORE
LASER_IMAGE_1_THRESHOLD
LASER_IMAGE_1_PASSED
Hologram

HOLOGRAM_SCORE
HOLOGRAM_THRESHOLD
HOLOGRAM_PASSED

Stereo laser portrait

STEREO_LASER_PORTRAIT_SCORE
STEREO_LASER_PORTRAIT_THRESHOLD
STEREO_LASER_PORTRAIT_PASSED

Laser image 2

LASER_IMAGE_2_SCORE
LASER_IMAGE_2_THRESHOLD
LASER_IMAGE_2_PASSED

Overall:

OVERALL_SCORE
OVERALL_THRESHOLD
OVERALL_PASSED

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: `Success` : The risk control process runs successfully. `Pending` : The risk control process is pending. `Failure` : The risk control process fails.
strategyPassResult	String	Specifies the result of risk check. Required if the risk control process runs successfully. Possible values and their meanings are as below: `PASS` : the identity proofing process passes the risk check. `VELOCITY_HIGH_RISK` : indicates that high risks are detected by the risk control engine. `ID_NETWORK_HIGH_RISK` : 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. Note: This risk is not reported when similar faces are detected associated with the same ID (identified by ID number) or the same user (identified by userid). `BLACKLIST_HIGH_RISK` : indicates that high risks are detected by the blacklist scanning. `AGE_MISMATCH_HIGH_RISK` : indicates that high risks are detected during age verifications.
idNetworkDetails	String	Optional. Specifies the detailed information about the ID Network output, this field is a JSON string that comes from the JSON serialization result of the IdNetworkDetails structure, please refer to IdNetworkDetails. Note: This field is specified only when the strategyPassResult field returns as `ID_NETWORK_HIGH_RISK`.
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} ] } }

IdNetworkDetails

Field name	Data type	Description
ekyc_id	String	Optional. Deprecated field. Specifies eKYC ID.
mobile	String	Optional. Deprecated field. Specifies mobile phone number.
reason_code	Array	Optional. Specifies causes of risk: `SIMILAR_FACE`: Similar faces are detected associated with multiple users (identified by userid). Note: This risk is not reported when similar faces are detected associated with the same user (identified by userid). `SAME_CERT_NO`: An ID is detected associated with multiple users (identified by userid).
type	String	Optional. Specifies the type of risks triggered: `Duplicated ID`: Multiple documents for the same person. `Fake ID`: Tampering with document information.
score	String	Optional. Reserved field. When the value of `type` is Duplicated ID, this field will be returned. Note: Please don't rely on this field.
user_id	String	Optional. Merchant user ID, or other identifiers that can be used to identify a specific user.

Note: The IDN embedded in RealID is a streamlined version of IDN that contains only some of IDN, and thus is called IDN Lite.

For all functions of IDN, please refer to IDN API Documentation.
To understand the differences between IDN Lite and IDN, please refer to IDN Lite vs IDN: What are the differences?

Introduction to risk types and reason codes

IdNetwork supports 2 types of major risk detection:

Fake ID (tampering with document information)
Duplicated ID (multiple documents for the same person)

The risk types and reason codes details are shown in the table below:

Risk type	Reason code	Description
Fake ID	SIMILAR_FACE	Same face, different ID numbers (same ID type).
Fake ID	SAME_CERT_NO	Same ID number (same ID type), different faces.
Duplicated ID	SIMILAR_FACE	Same face, different ID types.

Version

Date	Change log
28 March, 2024	New output parameter faceAttribute is added.
30 November, 2023	IdNetworkDetails and Introduction to risk types and reason codes are added
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	A new parameter, securityFeaturesResult, is added in the ExtIdInfo field of the response. The following two new OCR result keys are added for both current and new HKIDs: ISSUE_DATE LATEST_ISSUE_DATE
21 May, 2020	A new OCR result key, SYMBOLS, is added for current and new HKID. A new key, OTHER_CHECK, is added in the spoofResult map.
27 December, 2019	The letter case convention of the parameter name is updated.
06 December, 2019	Released.