compare

    #Overview

    API Name: ZOLOZ SaaS Face Compare API

    API URL: /api/v1/zoloz/facecompare/compare

    API Description: Providing the capability of similarity comparison between two given faces, along with the face liveness detection results.


    #Version

    Date

    Version

    Release Notes

    25 November, 2019

    1.0.0

    The first published version.

    29 November, 2019

    1.0.1

    remove liveness detection.


    #Request

    #Fields Specification

    Name

    Type

    Max Length

    Mandatory

    Default Value

    Value Range

    Description

    Sample Value

    bizId

    string

    32B

    true


    not null and not empty string

    business unique ID for tracing purpose

    "trans-abc-123"

    face1.content

    string

    1MB

    true


    not null and not empty string

    base 64 string of face image in jpg format.

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

    face1.rect

    string

    32B

    false

    null


    face coordinates in format "left,top,width,height"

    "123,45,234,621"

    face2.content

    string

    1MB

    true


    not null and not empty string

    base 64 string of face image in jpg format.

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

    face2.rect

    string

    32B

    false

    null


    face coordinates in format "left,top,width,height"

    "123,45,234,621"


    #Request Sample

    copy
    POST /api/v1/zoloz/facecompare/compare 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",
      "face1": {
        "content": "/9j/4AA..[omitted]..PxA=",
        "rect": "234,54,22,123"
      },
      "face2": {
        "content": "/9j/4AA..[omitted]..tvq=",
        "rect": "234,432,34,22"
      }
    }


    #Response

    #Fields Specification

    Name

    Type

    Mandatory

    Value Range

    Description

    Sample Value

    transactionId

    string

    true


    transaction id

    "G000000005FID20200304000000000001570702"

    score

    double

    true

    (0.0, 100.0)

    face comparison score

    88.2

    samePerson

    boolean

    true

    true, false

    are the two faces the same person based on algorithm 

    true

    result.resultCode

    string

    true


    result code

    "SUCCESS"

    result.resultStatus

    string

    true


    result status

    "S"

    result.resultMessage

    string

    true


    result message

    "success"


    The value range of "resultCode" at business level:

    resultCode

    Description

    PARAM_ILLEGAL

    bizId is null or empty string; livenessDetectMode doesn't equal to "NONE" or "NORMAL"; 

    UNABLE_GET_IMAGE

    the base64 string of face image is null or empty string or damaged; the face image is not in jpg format; no face detected in image;

    SUCCESS

    the comparison result is successfully returned, regardless whether face1 and face2 indicate the same person;

    SYSTEM_ERROR

    other internal errors;


    #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",
      "score": 88.2,
      "samePerson": true,
      "result": {
        "resultCode":"SUCCESS",
        "resultStatus":"S",
        "resultMessage":"success",
        "transactionId": "xxxxxx"
      }
    }



    #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

    PARAM_ILLEGAL

    bizId is null or empty string; livenessDetectMode doesn't equal to "NONE" or "NORMAL"; 

    UNABLE_GET_IMAGE

    the base64 string of face image is null or empty string or damaged; the face image is not in jpg format; no face detected in image;

    SUCCESS

    the comparison result is successfully returned, regardless whether face1 and face2 indicate the same person;

    SYSTEM_ERROR

    other internal errors;


    #RequestFaceImage Model

    Description: A data structure that represents an image with face.

    Fields Specification:

    Name

    Type

    Mandatory

    Default Value

    Value Range

    Description

    Sample Value

    content

    string

    true



    base 64 string of face image in jpg format.

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

    rect

    string

    false

    null


    face coordinates in format "left,top,width,height"

    "112,234,455,89"