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:

    Y : The image data needs to be returned in the response. 

    N : The image data does not need to be returned in the response. 

    By default, the value of N is used. 

    #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 SRefer 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": "N"
    }

    #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.31415926535897,
            "faceImg": "/9j/4AA..[omitted]..PxA=",
            "faceQuality": 97.61517973846627,
            "faceLivenessResult": "Success"
        },
        "extIdInfo": {
            "ekycResultDoc": "Pending",
            "docEdition": 1,
            "frontPageImg": "/9j/4AA..[omitted]..PxA=",
            "backPageImg": "/9j/4AA..[omitted]..PxA=",
            "ocrResult": {
                ...
            },
            "spoofResult": {
                "TAMPER_CHECK": "Y",
                "MATERIAL_CHECK": "Y",
                "SCREEN_RECAPTURE_CHECK": "Y",
                "OTHER_CHECK":,"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": "..."
        },
        "extCustomInfo": {
            ...
        }    
    }

    #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 running status 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

    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 Y and the face verification process runs successfully. 

    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.

    #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 running status 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. For example, for the current HKID, the value of this field is returned as 1, while for the new HKID, the value of this field is returned as 2

    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 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 Ythe document verification process runs successfully and it is required to upload the backside image of the identity document.

    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:

    • 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. 

    #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 running status 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, the face recognized is detected to relates to multiple identity documents, or an identity document is detected to relates to multiple faces. 

    idNetworkDetails

    String

    Optional. Specifies the detailed information about the ID network output. This field is specified only when the strategyPassResult field returns as ID_NETWORK_HIGH_RISK

    #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. 

    OTHER_CHECK

    String

    Required. Specifies the result of the other checks, including the security feature check and information validity check about the identity document itself. Possible values and their meanings are as below:

    • Y: indicates the other checks are passed.
    • N: indicates the other checks are not passed. 

    #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


    image.png

    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. 

    1. Optical variable ink
    • OPTICAL_VARIABLE_INK_SCORE: 70
    • OPTICAL_VARIABLE_INK_THRESHOLD: 60
    • OPTICAL_VARIABLE_INK_PASSED: True
    1. 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

    image.png

    Figure 2. A sample image of the new HKID

    Note: The sample image comes from https://www.smartid.gov.hk/en/Development-of-Hong-Kong-Identity-Cards/index.html.

    As Figure 2 shows, for the new HKID, security features are detected in terms of laser image1, hologram, stereo laser portrait, and laser image2.

    The following list shows the fields and value examples for each security feature and overall check result. 

    1. Laser image1
    • LASER_IMAGE_1_SCORE
    • LASER_IMAGE_1_THRESHOLD
    • LASER_IMAGE_1_PASSED
    • Hologram
    • HOLOGRAM_SCORE
    • HOLOGRAM_THRESHOLD
    • HOLOGRAM_PASSED
    1. Stereo laser portrait
    • STEREO_LASER_PORTRAIT_SCORE
    • STEREO_LASER_PORTRAIT_THRESHOLD
    • STEREO_LASER_PORTRAIT_PASSED
    1. Laser image 2
    • LASER_IMAGE_2_SCORE
    • LASER_IMAGE_2_THRESHOLD
    • LASER_IMAGE_2_PASSED

    Overall:

    • OVERALL_SCORE
    • OVERALL_THRESHOLD
    • OVERALL_PASSED

    #Version

    Date

    Change log

    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.