ID Recognition API

2021-02-26 07:34

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

Request

Fields Specification

Name	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	true		not null not empty string	document type, see definitions below.	"00000001003"
frontPageImage	string	1MB	true		not null not empty string	base64 string of front side of doc image.	"/9j/4AA..[omitted]..PxA="
backPageImage	string	1MB	false			base64 string of back side of doc image.	"/9j/4AA..[omitted]..PxA="

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="
}

Response

Fields Specification

Name	Type	Mandatory	Value Range	Description	Sample Value
transactionId	string	false		transaction id	copy `"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"
ocrResult	Map	false		ocr result map，please refer to appendix.
spoofResult	Map	false		anti-spoofing result map，please refer to appendix.
result	CommonResult	true		common result, please refer to appendix.

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",
  "recognitionResult": "Y",
  "ocrResult": {
		"ID_NUMBER": "xxxx",
		"COUNTRY": "xxxxx",
		"SEX": "M",
		"LAST_NAME": "xxxxx",
		"DATE_OF_BIRTH": "xxxxx",
		"FIRST_NAME": "xxxxx"
	},
  "spoofResult": {
		"TAMPER_CHECK": "Y",
		"MATERIAL_CHECK": "Y",
		"SCREEN_RECAPTURE_CHECK": "Y"
	}
  "result": {
    "resultCode":"SUCCESS",
    "resultStatus":"S",
    "resultMessage":"success"
  }
}

Appendix

CommonResult Model

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

Fields Specification:

Name	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;

Support DocType and Return OCR Result Key

Country/Region	Name	docType	pages	ocr result key
All countries	Passport	00000001003	1	LAST_NAME FIRST_NAME ID_NUMBER COUNTRY SEX DATE_OF_BIRTH
Philippines	UMID	00630000001	1	ID_NUMBER LAST_NAME FIRST_NAME MIDDLE_NAME SEX DATE_OF_BIRTH
Philippines	TIN	00630000002	1	ID_NUMBER LAST_NAME FIRST_NAME DATE_OF_BIRTH
Philippines	Driver’s License	00630000004	1	ID_NUMBER LAST_NAME FIRST_NAME MIDDLE_NAME SEX DATE_OF_BIRTH
Philippines	PHILHEALTH	00630000024	1	ID_NUMBER LAST_NAME FIRST_NAME MIDDLE_NAME DATE_OF_BIRTH
Philippines	SSS	00630000020	1	ID_NUMBER LAST_NAME FIRST_NAME MIDDLE_NAME DATE_OF_BIRTH
Malaysia	MyKad	00600000001	1	ID_NUMBER NAME DATE_OF_BIRTH
Indonesia	eKTP	00620000001	1	ID_NUMBER NAME DATE_OF_BIRTH
HK	Current HKID	08520000001	1	NAME NAME_CN SEX DATE_OF_BIRTH ID_NUMBER
HK	New HKID	08520000002	1	NAME NAME_CN SEX DATE_OF_BIRTH ID_NUMBER
Macao	Identity Card	08530000001	1	ID_NUMBER PLACE_OF_BIRTH SEX CNAME1 CNAME2 PNAME1 PNAME2 DATE_OF_EXPIRE DATE_OF_BIRTH
Bengal	NID/SmartCard	08800000001	2	ID_NUMBER BNAME_M BNAME_F BNAME BNAME_H DATE_OF_BIRTH NAME

Spoof Result

Spoof result values further explanation

Name	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"

ZOLOZ Team