ID Recognition API

#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

PhilippinesUMID

00630000001

1

ID_NUMBER

LAST_NAME

FIRST_NAME

MIDDLE_NAME

SEX

DATE_OF_BIRTH

Philippines

TIN00630000002

1

ID_NUMBER

LAST_NAME

FIRST_NAME

DATE_OF_BIRTH

PhilippinesDriver’s License00630000004

1

ID_NUMBER

LAST_NAME

FIRST_NAME

MIDDLE_NAME

SEX

DATE_OF_BIRTH

PhilippinesPHILHEALTH00630000024

1

ID_NUMBER

LAST_NAME

FIRST_NAME

MIDDLE_NAME

DATE_OF_BIRTH

PhilippinesSSS

00630000020

1

ID_NUMBER

LAST_NAME

FIRST_NAME

MIDDLE_NAME

DATE_OF_BIRTH

Malaysia MyKad00600000001

1

ID_NUMBER

NAME

DATE_OF_BIRTH

Indonesia

eKTP00620000001

1

ID_NUMBER

NAME

DATE_OF_BIRTH

HK

Current HKID08520000001

1

NAME

NAME_CN

SEX

DATE_OF_BIRTH

ID_NUMBER

HK

New HKID08520000002

1

NAME

NAME_CN

SEX

DATE_OF_BIRTH

ID_NUMBER

Macao

Identity Card08530000001

1

ID_NUMBER

PLACE_OF_BIRTH

SEX

CNAME1

CNAME2

PNAME1

PNAME2

DATE_OF_EXPIRE

DATE_OF_BIRTH

Bengal

NID/SmartCard08800000001

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