recognize
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. |
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 | "00000001003" |
autoDocTypes | List<String> | 200 | false | null | Specify list of document types. Please provide either
The value of items in | ["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:
| "STANDARD" | |
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" | |
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. Specify whether to perform information checks within a DOC spoofing check. information checks are only applicable for selected documents. |
consistencyCheck | List<ConsistencyCheckItem> | - | null | Optional. Specify whether to perform consistency checks within a DOC spoofing check. consistency checks are only applicable for selected documents. |
allowExpiredDocument | String | - | Different document types have different default values:
| Optional. Specifies whether expired documents are allowed. The following values are supported:
Note: Invalid values will fall back to the default option and pause the ID Recognition process when an expired document is detected. |
enableOCR | String | - | N | Optional. Whether to enable the OCR function. The values are as follows: |
spoofMode | String | 10 | CLOSED | Optional. This parameter refers to document anti-spoofing levels, defined as follows:
|
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 | Mykad / Malaysia / 00600000001 / ID_NUMBER
|
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. | - |
details | List<String> | refer to supported ocr fileds of each docType | specify ocr field in details for consistency check.
| MyVisa / Malaysia / 00600000011 /
|
Passport (both MRZ and VIZ) / CHN, HKG, TWN, MAC, PHL, SGP, MYS / 00000001006 /
|
Request Sample
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="
"productConfig": {
"consistencyCheck": [
{
"type": "commonConsistencyCheck"
},
{
"details": [
"NAME",
"SEX"
],
"type": "mrzVisualConsistencyCheck"
}
],
"pageInfoCheck": [
{
"name": "id"
},
{
"name": "symbol"
},
{
"name": "name"
}
],
"allowExpiredDocument": "Y",
"enableOCR":"Y",
"spoofMode":"STANDARD"
},
"operationMode": "CLOSED",
"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 | |
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 UNKNOWN | recognition error code | "BLUR" |
ocrResult | Map | false | ocr result map,please refer to appendix. | ||
ocrResultDetail | Map<String, OcrResultDetail> | false | OCR result details. This field is returned only when | ||
spoofResult | Map | false | anti-spoofing result map,please refer to appendix. | ||
result | true | common result, please refer to appendix. |
Response Sample
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",
"spoofResult": {
"TAMPER_CHECK": "Y",
"SECURITY_FEATURE_CHECK": "Y",
"MATERIAL_CHECK": "Y",
"INFORMATION_CHECK": "Y",
"SCREEN_RECAPTURE_CHECK": "Y"
}
}
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" |