recognize

2024-11-01 09:54

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, see Document types supported and OCR results returned. Note: Please provide either `docType` or `autoDocTypes`.	"00000001003"
autoDocTypes	List<String>	200	false	null		Specifies list of document types. Please provide either `docType` or `autoDocTypes`. When `autoDocTypes` is provided, ZOLOZ will automatically classify the document uploaded. Notes： passport currently is not supported for auto classified. 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"]
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.
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
details	List<String>	refer to supported ocr fileds of each docType		Passport (both MRZ and VIZ) / CHN, HKG, TWN, MAC, PHL, SGP, MYS / 00000001006 / ID_NUMBER COUNTRY_CODE EXPIRY_DATE DATE_OF_BIRTH

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>	should be the same as the default country code.	when type is passportCountryCheck, valueRange should not be empty. Refer to allowed value of supported docType.	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 item 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"
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	recognition error code	"BLUR"
recognitionErrorDescription	String	false		Specifies doc verification failure reason.
ocrResult	Map	false		ocr result map，please refer to appendix.
ocrResultDetail	Map<String, OcrResultDetail>	false		OCR result details. This field is returned only when `mrzVisualConsistencyCheck` is provided.	Response Sample.
spoofResult	Map	false		anti-spoofing result map，please refer to appendix.
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": "xxx",
  "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"
  },
  "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"
    }
  },
  "recognitionResult": "Y",
  "recognitionErrorCode": "BLUR",
  "recognitionErrorDescription": "xxxxx",
  "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"