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