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.

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

Unique business ID for tracing purposes.

"trans-abc-123"

userId 

string

64B

false

null

Merchant user ID, or other identifiers that can be used to identify a specific user.

For example, mobile phone number, email address and so on. It is strongly recommended to pre-desensitize the value of the userId field; for example, by hashing the value.

"userid_1234"

face1.content

string

1MB

true

not null and not empty string

Base64 encoded face image which supports JPG/JPEG/PNG/BMP formats. 

Notes:

  • Pass selfie image for this parameter. Accuracy of the recognition result cannot be guaranteed when a document with face image is passed.
  • When using the pure API mode to upload PNG images, you will need to turn off the Alpha channel so that the PNG image can be displayed properly in the Portal. Please refer to the FAQs for more information. 

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

face1.rect

string

32B

false

null

Face coordinates in "left,top,width,height" format.

"123,45,234,621"

face2.content

string

1MB

true

not null and not empty string

Base64 encoded face image which supports JPG/JPEG/PNG/BMP formats. 

Note: When using the pure API mode to upload PNG images, you will need to turn off the Alpha channel so that the PNG image can be displayed properly in the Portal. Please refer to the FAQs for more information. 

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

face2.rect

string

32B

false

null

Face coordinates in "left,top,width,height" format.

"123,45,234,621"

sourceOfFace2

string

32B

false

SELFIE

SELFIE or 00000001007 or valid docType

Note: For the specific valid docType, please refer to Document types supported and OCR results returned.

Specify whether face2.content is a selfie image or a face image from a document.

  • SELFIE: a selfie image
  • valid docType: a face image from a document which matches docType
  • 00000001007: a face image from a document not supported by ZOLOZ now

Note: If the type of face2.content does not match the value of this field, the matching result will be inaccurate.

"SELFIE"

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",
  "userId":"userid_1234",
  "face1": {
    "content": "/9j/4AA..[omitted]..PxA=",
    "rect": "234,54,22,123"
  },
  "face2": {
    "content": "/9j/4AA..[omitted]..tvq=",
    "rect": "234,432,34,22"
  },
  "sourceOfFace2": "SELFIE"
}

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

INVALID_ARGUMENT

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"