recognize

2022-02-08 14:05

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

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 Document types supported and OCR results returned.	"00000001003"
frontPageImage	string	5MB	true		not null not empty string	base64 string of front side of doc image in jpg format.	"/9j/4AA..[omitted]..PxA="
backPageImage	string	5MB	false			base64 string of back side of doc image in jpg format.	"/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	"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;

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"