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"