ZOLOZZOLOZDOCS

asynccompare

Overview

  • API URL: /api/v1/zoloz/facecompare/asynccompare
  • API Description: The ZOLOZ Face Compare asynccompare API initializes an asynchronous face comparison request. When you need to frequently call the compare API, it is recommended to use the asynccompare API to avoid response timeouts due to network fluctuations. After the API call completes, you can asynchronously obtain the face comparison results using the asynccheckresult API.

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

5MB

true

not null and not empty string

The face images are encoded in Base64 and support JPG, JPEG, PNG, and BMP formats.

Note:

  • This parameter defaults to a live face image. If you pass in a document face image, the accuracy of the recognition results cannot be guaranteed.

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

5MB

true

not null and not empty string

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

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

Note：Currently, the total size of the two images, face1.content and face2.content, must not surpass 5MB. Should it exceed this limit, please compress the images prior to uploading them in order to prevent system errors.

Request Sample

copy
POST /api/v1/zoloz/facecompare/asynccompare HTTP/1.1
Content-Type: application/json; charset=UTF-8
Client-Id: 5X67656YXXXXXX
Request-Time: 2024-01-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

result.resultCode

string

true

result code

"SUCCESS"

result.resultStatus

string

true

result status

"S"

result.resultMessage

string

true

result message

"success"

transactionId

string

true

transaction id

Note: The system will only return the transactionId after the transaction enters the processing stage. If an error occurs before the transaction begins processing, the system will not return a transactionId. This includes, but is not limited to, the following situations:

  • Invalid request parameters, such as incorrect input format or missing required parameters.
  • The request fails to reach the server successfully, such as due to network issues or gateway failures.
  • The request is denied due to system rate limiting.

"G000000005FID20200304000000000001570702"

Result

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

Invalid input parameters.

  • bizId is null or an empty string.
  • The content of face1 or face2 is empty, or the encoding format is incorrect.

PROCESSING

Processing in Progress.

SYSTEM_ERROR

Other internal errors.

Response Sample

copy
HTTP/1.1 200 OK
Content-Type: application/json; charset=UTF-8
Response-Time: 2024-01-19T21:56:15-0800
Signature: algorithm=RSA256, signature=xxxxxxxxxxxxxxxxxx

{
  "transactionId": "G000000005FID2020030400000000000157****",
  "result": {
    "resultCode":"PROCESSING",
    "resultStatus":"S",
    "resultMessage":"It is still under processing"
  }
}