asynccheckresult

2025-05-07 07:14

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 Note: The system will only return the `transactionId` after the transaction enters the processing stage. If an error occurs before the transaction begins processing, the system will not return a `transactionId`. This includes, but is not limited to, the following situations: Invalid request parameters, such as incorrect input format or missing required parameters. The request fails to reach the server successfully, such as due to network issues or gateway failures. The request is denied due to system rate limiting.	"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`~`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.	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" }
deeperResult	String	Optional. Deeper document detection results. The returned Deeper detection results are provided only when deeperMode is not `CLOSED`. The return values are as follows: `Y`: No AIGC attack risk detected. `N`: AIGC attack risk detected.	"N"
deeperResultDescription	String	Optional. Detailed description of Deeper document detection results. The detailed description of the Deeper detection results is provided only when `deeperMode` is not `CLOSED` and `deeperResult` is N.	"deepfake risk, AIGC feature blacklib"
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"
  },
  "deeperResult": "N",
  "deeperResultDescription": "deepfake risk, AIGC feature blacklib",
  "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"