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

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

The front side of the document image supports Base64 encoded JPG/JPEG/PNG/BMP formats. 

Note: When using the pure API mode to upload PNG images, you will need to turn off the Alpha channel so that the PNG image can be displayed properly in the Portal. Please refer to the FAQs for more information. 

"/9j/4AA..[omitted]..PxA="

backPageImage

string

5MB

false

The back side of the document image supports Base64 encoded JPG/JPEG/PNG/BMP formats.

Note: When using the pure API mode to upload PNG images, you will need to turn off the Alpha channel so that the PNG image can be displayed properly in the Portal. Please refer to the FAQs for more information. 

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