recognize

2025-04-11 03:08

Overview

API Name: ZOLOZ SaaS ID Recognition API

API URL: /api/v1/zoloz/idrecognition/recognize

API Description: Providing the Optical Character Recognition (OCR) functionality for most of documents like passport, ID card and driving license, etc., along with the anti-spoofing results for the documents.

Version

Date	Version	Release Notes
25 November, 2019	1.0.0	The first published version.
28 November, 2019	1.0.1	update api content
29 November, 2019	1.0.2	update ocr info
23 December, 2021	1.0.3	update image size limit
15 July, 2024	1.0.4	A new parameter, consistencyCheck, is added in productConfig.
27 Sep,2024	1.0.5	A new parameter, passportCountryCheck, is added in consistencyCheck of productConfig.

Request

Fields Specification

Field name	Data type	Max length	Mandatory	Default Value	Value Range	Description	Sample Value
bizId	string	32B	true		not null not empty string	Business unique ID for tracing purpose.	"trans-abc-1234"
docType	string	32B	false	null	not null not empty string	Document type. Supported category C documents: See Document types supported and OCR results returned Supported category B documents: See Business document types supported and OCR results returned Note: `docType` specifies the specific document type, while `autoDocTypes` and `autoDocCategory` are used for automatic document classification. The three parameters are mutually exclusive; only one can be passed at a time.	"00000001003"
autoDocTypes	List<String>	200	false	null		Specifies list of document types. The parameters `docType`, `autoDocTypes`, and `autoDocCategory` are mutually exclusive; only one can be passed at a time. When autoDocTypes is provided, ZOLOZ will automatically classify the document uploaded. Notes： The passport auto-classification feature is supported, but it is only available in the Native SDK. Singapore Citizen card(00650000001) and PR card(00650000002) will be both classified as Singapore Citizen card. If the uploaded document could not be classified or it is not included in autoDocTypes list, NO_REQUIRED_ID will be returned. The value of items in autoDocTypes must be a valid docType. Supported document types, see Document types supported and OCR results returned.	["08520000001","08520000002"]
autoDocCategory	List<String>	-	true	null		Specifies list of document types. The parameters `docType`, `autoDocTypes`, and `autoDocCategory` are mutually exclusive; only one can be passed at a time. If you pass `autoDocCategory`, ZOLOZ will automatically classify the uploaded documents. The supported document categories are as follows: `PASSPORT`: Passport `DRIVING_LICENSE`: Driving License `ID_CARD`: ID Card `RESIDENCE_PERMIT`: `Residence` Permit `VISA`: Visa `ALL`: All documents If ZOLOZ cannot classify the uploaded document or the classified document type is not in `autoDocCategory`, it will return NO_REQUIRED_ID. Note: Please be cautious that if `autoDocCategory` is in use, the `docType` classified could be a new type supported by ZOLOZ. It also means `certType` and `docCategory` in checkresult response could fall into a new type as we continue to expand the doc coverage globally. For example, when `autoDocCategory` in request is `ALL`, based on the doc submitted by user, after auto classification, the `certType` could be a new doc type (e.g. `00000001001` and `NEW_CATEGORY`). (For illustration only) Please take necessary compatible actions for integration. For example, do not strongly validate the returned `certType` and `docCategory`.	"ID_CARD"
frontPageImage	string	5MB	true		not null not empty string	The front side of the document image supports Base64 encoded JPG/JPEG/PNG/BMP formats.	"/9j/4AA..[omitted]..PxA="
backPageImage	string	5MB	false			The back side of the document image supports Base64 encoded JPG/JPEG/PNG/BMP formats.	"/9j/4AA..[omitted]..PxA="
operationMode	String	32	false	STANDARD		Specifies the operation mode where the identity proofing process runs. The following values are supported: `CLOSED`: All the algorithms and risk control rules are not applied. You can use this operation mode in the test phase so that the algorithms and risk controls rules do not affect the test process. `STANDARD`: A standard recommended level is applied. `LOOSE`: A relatively looser level is applied. You can use this operation mode in low-risk scenarios. `STRICT`: A relatively stricter level is applied. You can use this operation mode in high-risk scenarios.	"STANDARD"
sceneCode	String	64	false	null		Specifies the business scene for data analysis purpose. If you want to distinguish the data performance of different scenes, it is recommended to set the `sceneCode` field to different values according to your business purpose; for example, login, riskVerify, payment, changePassword. Setting this value will not have business impacts.	"changePassword"
userId	String	64	false	null		Merchant user ID, or other identifiers that can be used to identify a specific user. For example, mobile phone number, email address and so on. It is strongly recommended to pre-desensitize the value of the userId field; for example, by hashing the value.	"123456abcd"
extraImageControlList	List<String>	-	false	null		Optional. Specifies whether to return extra images. The following values are supported: `CROPPED_FACE_FROM_DOC`: return the cropped face area of the doc image. Note: Extra images will only be returned if the document image provided in `frontPageImage` contains a face and is successfully cropped; otherwise, `extraImages` will return an empty string " ".	[ "CROPPED_FACE_FROM_DOC" ]
productConfig	ProductConfig	-	false	null		Optional. Specifies finer controls for the IDR product. For more information, see productConfig.	{ "consistencyCheck": [ { "type": "commonConsistencyCheck" }, { "details": [ "NAME", "SEX" ], "type": "mrzVisualConsistencyCheck" } ] }

Note: Currently, the total size of the two images, frontPageImage and backPageImage, must not surpass 5MB. Should it exceed this limit, please compress the images prior to uploading them in order to prevent system errors.

productConfig

The following table shows the fields that can be specified in the productConfig data model.

Field name	Data type	Max length	Default Value	Description
pageInfoCheck	Array	-	null	Optional. Specifies page information check in the DOC spoofing check. For detailed inspection items, refer to the DOC spoofing check component. Note: Page information check is only applicable to Hong Kong, China identity cards and Malaysia Mykad.
consistencyCheck	List<ConsistencyCheckItem>	-	null	Optional. Specifies whether to perform consistency checks within a DOC spoofing check. consistency checks are only applicable for selected documents. An array of supported information check components needs to be specified if consistency check is expected. To understand the valid values for this field, please refer to consistency check data structure.
allowExpiredDocument	String	-	Different document types have different default values: `Y`: This is the default value for all documents except Passport (docType=00000001003). `N`: This is the default value for Passport (docType=00000001003).	Optional. Specifies whether expired documents are allowed. The following values are supported: `Y`: Allow expired documents. `N`: Pause ID Recognition process when an expired document is detected. Note: Invalid values will fall back to the default option and pause the ID Recognition process when an expired document is detected.
cropFaceImageFromDoc	String	1	N	Optional. Specifies whether to crop the face area of the captured doc image. Valid values include: `Y`: Crop an additional face image from the doc image `N`: Default value. Do not crop
enableOCR	String	-	N	Optional. Whether to enable the OCR function. The values are as follows: ● `Y`: Enabled ● `N`: Not enabled
spoofMode	String	10	CLOSED	Optional. This parameter refers to document anti-spoofing levels, defined as follows: `CLOSED`: All algorithms are not applied. You can use this anti-spoofing detection mode in the test phase so that the algorithms do not affect the testing process. `STANDARD`: A standard recommended level is applied. `LOOSE`: Reserved value, not currently supported for use. `STRICT`: Reserved value, not currently supported for use.

ConsistencyCheckItem data structure

commonConsistencyCheck

Field name

Data type

Value range

Description

Supported ID / Country or Region / docType / OCR field to check

type

String

commonConsistencyCheck

Consistency check of OCR field within DOC spoofing check

Mykad / Malaysia / 00600000001 / ID_NUMBER

front page: ID_NUMBER
back page: ID_NUMBER_BACK first 12 digit

mrzVisualConsistencyCheck

Field name	Data type	Value range	Description	Supported ID / Country or Region / docType / OCR field to check
type	String	mrzVisualConsistencyCheck	Consistency check of OCR field which has both MRZ (machine readable zone) and VIZ (visual inspection zone) within DOC spoofing check	-
details	List<String>	refer to supported ocr fileds of each docType	Specifies ocr field in details for consistency check. When `type` is set as `mrzVisualConsistencyCheck`, `details` field is required and should not be null. Only allow to input OCR fields supported by the ID document.	MyVisa / Malaysia / 00600000011 / NAME SEX
				Passport (both MRZ and VIZ) / CHN, HKG, TWN, MAC, PHL, SGP, MYS / 00000001006 / ID_NUMBER COUNTRY_CODE EXPIRY_DATE DATE_OF_BIRTH
				Travel Permit for Hong Kong and Macau / China / 00860000011 ID_NUMBER DATE_OF_EXPIRY

passportCountryCheck

Field name	Data type	Value range	Description	Supported ID / Country or Region / docType / OCR field to check / default country code
type	String	passportCountryCheck	Checks that the `COUNTRY_CODE` in the OCR result is consistent with the country detected by the system.
valueRange	List<String>	Each value should be the same as the default country code.	The COUNTRY_CODE in the OCR result should be within the valueRange. When the type is set to passportCountryCheck, the valueRange field must be provided. For the supported valueRange of each document, please refer to Document types supported and OCR results returned	For below docTypes, valueRange should be a list of its default country or region code China Passport / 00860000888 / COUNTRY_CODE / CHN China Taiwan Passport / 08860000002 / COUNTRY_CODE / TWN China Macao Passport / 08530000002 / COUNTRY_CODE / CHN Philippines Old Passport / 00630000031 / COUNTRY_CODE / PHL Philippines New Passport /00630000032 / COUNTRY_CODE / PHL
valueRange	List<String>	Each value should comply with ISO_3166-1_alpha-3		For below docTypes, valueRange should be a list, and each item should comply with ISO_3166-1_alpha-3 Internaltional Passport / 00000001003 / COUNTRY_CODE Passport with viz / 00000001006 / COUNTRY_CODE

Request Sample

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

{
  "bizId": "trans-test-1234",
  "docType": "00000001003",
  "frontPageImage": "/9j/4AA..[omitted]..PxA=",
  "backPageImage": "/9j/4AA..[omitted]..PxA=",
   "extraImageControlList":[
      "CROPPED_FACE_FROM_DOC"
  ],
  "productConfig": {
    "consistencyCheck": [
      {
        "type": "commonConsistencyCheck"
      },
      {
        "details": [
          "NAME",
          "SEX"
        ],
        "type": "mrzVisualConsistencyCheck"
      },
      ,
      {
        "valueRange": [
          "CHN",
          "PHL"
        ],
        "type": "passportCountryCheck"
      }
    ],
     "pageInfoCheck": [
            {
                "name": "id"
            },
            {
                "name": "symbol"
            },
            {
                "name": "name"
            }
        ],
     "allowExpiredDocument": "Y",
     "cropFaceImageFromDoc": "Y",
     "enableOCR":"Y",
     "spoofMode":"STANDARD"
  },
  "operationMode": "CLOSED",
  "sceneCode": "changePassword",
  "userId": "123456abcd"
}

Response

Fields Specification

Field name	Data type	Mandatory	Value Range	Description	Sample Value
certType	String	false		ID type. Specifies the type of the identity document. Required if the document verification process runs successfully.	"00600000001"
docCategory	String	false		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	false		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
transactionId	string	false		transaction id	"G000000005FID20200304000000000001570702"
recognitionResult	string	false	"Y" "N"	recognition result	"Y"
recognitionErrorCode	string	false	NO_REQUIRED_ID BLUR NO_FACE_DETECTED NOT_REAL_DOC EXPOSURE UNKNOWN	Details of document recognition failure: `NO_REQUIRED_ID`: The document image does not match the specified document type. `BLUR`: The document image is blurry. `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	false		Specifies doc verification failure reason.	"passport country code check failed."
ocrResult	Map	false		ocr result map，please refer to appendix.
ocrResultFormat	Map	false		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>	false		OCR result details. This field is returned only when `mrzVisualConsistencyCheck` is provided.	Response Sample.
countryCode	String	false		The country code recognized through OCR is returned only when the `docCategory` is a passport.	"CHN"
spoofResult	Map	false		anti-spoofing result map，please refer to appendix.	{ "TAMPER_CHECK": "Y", "MATERIAL_CHECK": "Y", "SCREEN_RECAPTURE_CHECK": "Y", "INFORMATION_CHECK": "Y", "SECURITY_FEATURE_CHECK": "Y" }
result	CommonResult	true		common result, please refer to appendix.
extraImages	Map<String,String>	false		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": "G000000005FID20200304000000000001570702",
  "result": {
    "resultCode": "SUCCESS",
    "resultMessage": "success",
    "resultStatus": "S"
  },
  "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="
  }
}

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"