ZOLOZZOLOZDOCS

      Face Compare API

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




      ZOLOZ Team