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


#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

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

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