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"