asynccheckresult

Overview

  • API URL: POST /api/v1/zoloz/idrecognition/asynccheckresult
  • API Description: The ZOLOZ ID Recognition asynccheckresult API is used to asynchronously obtain document verification results. When calling this API, you must pass the transaction ID returned by the asyncrecognize API.

Request

Fields Specification

Field name

Data type

Max length

Default Value

Description

Example

transactionId

String

64B

-

Required. The transaction ID returned by the asyncrecognize API.

"G000000005FID2020030400000000000157****"

extraImageControlList

List<String>

-

null

Optional. Specify whether to return additional images. The supported image types are as follows:

  • CROPPED_FACE_FROM_DOC: Crops and returns the face region from the document image.

Note: Additional images will only be returned if the document image in frontPageImage contains a face and the cropping is successful; otherwise, extraImages will return an empty string "".

[

"CROPPED_FACE_FROM_DOC"

]

Request Sample

copy
POST /api/v1/zoloz/idrecognition/asynccheckresult HTTP/1.1
Content-Type: application/json; charset=UTF-8
Client-Id: 5X67656YXXXXXX
Request-Time: 2024-01-04T12:08:56+05:30
Signature: algorithm=RSA256, signature=xxxxxxxxxxxx

{
  "transactionId": "G000000005FID2020030400000000000157****",
  "extraImageControlList":[
      "CROPPED_FACE_FROM_DOC"
  ]
}

Response

Fields Specification

Field name

Data type

Description

Example

result

CommonResult

Required. Common result, please refer to appendix.

{

"resultCode": "PROCESSING",

"resultStatus": "S",

"resultMessage": "It is still under processing"

}

transactionId

String

Required. Transaction id

"G000000005FID2020030400000000000157****"

certType

String

Optional. ID type.

Specifies the type of the identity document. Required if the document verification process runs successfully.

"00600000001"

docCategory

String

Optional. Specifies the type of the identity document.

  • PASSPORT: Passport
  • DRIVING_LICENSE: Driving License
  • ID_CARD: ID Card
  • RESIDENCE_PERMIT: Residence Permit
  • VISA: Visa
  • OTHERS: Other

"PASSPORT"

docEdition

Integer

Optional. Specifies the edition of the identity document.

1

recognitionResult

String

Optional. Recognition result

  • Y: Success
  • N: Failure

"Y"

recognitionErrorCode

String

Optional. Details of document recognition failure:

  • NO_REQUIRED_ID: The document image does not match the specified document type.
  • BLUR: The document image is blurred.
  • NO_FACE_DETECTED: No face detected on the document.
  • NOT_REAL_DOC: Document anti-counterfeiting detection failed.
  • EXPOSURE: The document image is overexposed.
  • UNKNOWN: Other errors.

"BLUR"

recognitionErrorDescription

String

Optional. Specifies doc verification failure reason.

"passport country code check failed."

ocrResult

Map

Optional. Ocr result map,please refer to Document types supported and OCR results returned.

{

"ID_NUMBER": "xxxx",

"COUNTRY": "xxxxx",

"SEX": "M",

"LAST_NAME": "xxxxx",

"DATE_OF_BIRTH": "xxxxx",

"FIRST_NAME": "xxxxx"

}

ocrResultFormat

Map

Optional. The standardized OCR output results can be found in the Notification on the Standardization of OCR Output Field Names.

{

"NUMBER": "12345",

"GENDER": "M"

}

ocrResultDetail

Map<String, OcrResultDetail>

Optional. OCR result details. This field is returned only when mrzVisualConsistencyCheck is provided.

Reference Response Sample

countryCode

String

Optional. The country code recognized through OCR is returned only when the docCategory is a passport.

"CHN"

spoofResult

Map

Optional. Anti-spoofing result map,please refer to spoofResult.

{

"TAMPER_CHECK": "Y",

"MATERIAL_CHECK": "Y",

"SCREEN_RECAPTURE_CHECK": "Y",

"INFORMATION_CHECK": "Y",

"SECURITY_FEATURE_CHECK": "Y"

}

extraImages

Map<String,String>

Optional. Specifies extra images that should be returned, and this field can be 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 "".

{

"CROPPED_FACE_FROM_DOC": "/9j/4AA..[omitted]..PxA="

}

Response Sample

copy
HTTP/1.1 200 OK
Content-Type: application/json; charset=UTF-8
Response-Time: 2019-11-19T21:56:15-0800
Signature: algorithm=RSA256, signature=xxxxxxxxxxxxxxxxxx

{
  "transactionId": "G000000005FID2020030400000000000157****",
  "certType": "00600000001",
  "docCategory": "PASSPORT",
  "docEdition": 1,
  "ocrResult": {
    "COUNTRY_CODE_IN_ISO": "Y",
    "LOCAL_NAME": "xxxx",
    "ID_NUMBER": "xxxx",
    "MAC_ID": "",
    "COUNTRY": "xxxx",
    "SEX": "M",
    "LAST_NAME": "xxxx",
    "HK_ID": "",
    "DATE_OF_BIRTH": "xxxx",
    "FIRST_NAME": "xxxx",
    "EXPIRY_DATE": "xxxx",
    "COUNTRY_CODE": "xxxx"
  },
  "ocrResultFormat": {
    "NUMBER": "12345",
    "GENDER": "M"
  },
  "ocrResultDetail": {
    "MRZ_MAC_ID": {
      "name": "MAC_ID",
      "source": "MRZ",
      "value": ""
    },
    "MRZ_COUNTRY_CODE_IN_ISO": {
      "name": "COUNTRY_CODE_IN_ISO",
      "source": "MRZ",
      "value": "Y"
    },
    "MRZ_ID_NUMBER": {
      "name": "ID_NUMBER",
      "source": "MRZ",
      "value": "xxxx"
    },
    "VISUAL_ID_NUMBER": {
      "name": "ID_NUMBER",
      "source": "VISUAL",
      "value": "xxxx"
    },
    "MRZ_DATE_OF_BIRTH": {
      "name": "DATE_OF_BIRTH",
      "source": "MRZ",
      "value": "xxxx"
    },
    "MRZ_COUNTRY_CODE": {
      "name": "COUNTRY_CODE",
      "source": "MRZ",
      "value": "xxxx"
    },
    "MRZ_EXPIRY_DATE": {
      "name": "EXPIRY_DATE",
      "source": "MRZ",
      "value": "xxxx"
    },
    "MRZ_FIRST_NAME": {
      "name": "FIRST_NAME",
      "source": "MRZ",
      "value": "xxxx"
    },
    "MRZ_HK_ID": {
      "name": "HK_ID",
      "source": "MRZ",
      "value": ""
    },
    "MRZ_SEX": {
      "name": "SEX",
      "source": "MRZ",
      "value": "M"
    },
    "VISUAL_LOCAL_NAME": {
      "name": "LOCAL_NAME",
      "source": "VISUAL",
      "value": "xxxx"
    },
    "VISUAL_EXPIRY_DATE": {
      "name": "EXPIRY_DATE",
      "source": "VISUAL",
      "value": "xxxx"
    },
    "MRZ_LAST_NAME": {
      "name": "LAST_NAME",
      "source": "MRZ",
      "value": "xxxx"
    },
    "VISUAL_COUNTRY_CODE": {
      "name": "COUNTRY_CODE",
      "source": "VISUAL",
      "value": "xxxx"
    },
    "MRZ_COUNTRY": {
      "name": "COUNTRY",
      "source": "MRZ",
      "value": "xxxx"
    }
  },
  "countryCode": "CHN",
  "recognitionResult": "Y",
  "recognitionErrorCode": "BLUR",
  "recognitionErrorDescription": "passport country code check failed.",
  "spoofResult": {
    "TAMPER_CHECK": "Y",
    "SECURITY_FEATURE_CHECK": "Y",
    "MATERIAL_CHECK": "Y",
    "INFORMATION_CHECK": "Y",
    "SCREEN_RECAPTURE_CHECK": "Y"
  },
  "extraImages": {
      "CROPPED_FACE_FROM_DOC": "/9j/4AA..[omitted]..PxA="
  },
  "result": {
    "resultCode":"SUCCESS",
    "resultStatus":"S",
    "resultMessage":"Success"
  }
}

Appendix

CommonResult Model

Description: A unified data structure that indicates the status of API invocation.

Fields Specification:

Field name

Data type

Mandatory

Value Range

Description

Sample Value

resultCode

string

true

result code

"SUCCESS"

resultStatus

string

true

"S": successful

"F": failed

result status

"S"

resultMessage

string

true

result description

"success"

The value range of "resultCode"at business level:

resultCode

Description

SUCCESS

success

SYSTEM_ERROR

other internal errors;

INVALID_ARGUMENT

input parameters are illegal;

Spoof Result

Spoof result values further explanation

Field name

Data type

Mandatory

Value Range

Description

Sample Value

TAMPER_CHECK

string

true

"Y": ok

"N": not ok

Check whether an ID is modified or not

"Y"

MATERIAL_CHECK

string

true

"Y": ok

"N": not ok

Check an ID's material is correct or not,

will return false once ID is black and white

"Y"

SCREEN_RECAPTURE_CHECK

string

true

"Y": ok

"N": not ok

Check if it is an ID recaptured from the screen

"Y"

INFORMATION_CHECK

string

false

"Y": ok

"N": not ok

Identity document information verification status.

Note: Currently, only Hong Kong Identity Cards are supported. The system verifies information on the identity card according to government regulations, such as the identity card number.

"Y"

SECURITY_FEATURE_CHECK

string

false

"Y": ok

"N": not ok

Identity document anti-counterfeit security feature detection status.

Note: Currently, only Hong Kong Identity Cards are supported. This detection verifies certain security features on the identity card to identify counterfeit documents.

"Y"