Face Compare

Overview

The face comparison endpoints let you determine whether two base64-encoded images contain the same person. The liveness variant also checks whether each image is of a live person (not a photo of a photo).

POST /Citizen/FaceCompare

Compares two face images and returns a match result with confidence score.

curl -X POST "https://citizen.uat.securecitizen.cloud/Citizen/FaceCompare" \
  -H "Authorization: Bearer <access_token>" \
  -H "Content-Type: application/json" \
  -d '{
    "ConsentReceived": true,
    "Face1": "<base64_image_1>",
    "Face2": "<base64_image_2>",
    "CRef": "REF00001"
  }'

Request Fields

Field	Type	Required	Description
`ConsentReceived`	boolean	Yes	Must be `true`
`Face1`	string	Yes	Base64-encoded first face image
`Face2`	string	Yes	Base64-encoded second face image
`CRef`	string	No	Your transaction reference

Response

{
  "VerifyResult": {
    "isIdentical": true,
    "confidence": 0.98
  },
  "trackingNumber": "00000000-0000-0000-0000-000000000000",
  "RequestedBy": "string",
  "AuthorizedBy": "string",
  "CRef": "REF00001",
  "Status": "Success",
  "Message": "string"
}

Field	Description
`VerifyResult.isIdentical`	`true` if the two faces are determined to be the same person
`VerifyResult.confidence`	Confidence score of the match (0–1, higher is more confident)
`trackingNumber`	Tracking number of the transaction
`RequestedBy`	Who requested the data
`AuthorizedBy`	Who authorised the provision of the data

Face Compare with Liveness

POST /Citizen/FaceCompareWithLiveness

Compares two face images and runs a liveness check on each image.

curl -X POST "https://citizen.uat.securecitizen.cloud/Citizen/FaceCompareWithLiveness" \
  -H "Authorization: Bearer <access_token>" \
  -H "Content-Type: application/json" \
  -d '{
    "ConsentReceived": true,
    "Face1": "<base64_image_1>",
    "Face2": "<base64_image_2>",
    "face1Meta": "Android",
    "face2Meta": "Android",
    "CRef": "REF00001"
  }'

Request Fields

Field	Type	Required	Description
`ConsentReceived`	boolean	Yes	Must be `true`
`Face1`	string	Yes	Base64-encoded first face image
`Face2`	string	Yes	Base64-encoded second face image
`face1Meta`	string	No	Device type for `Face1`: `Desktop`, `Ios`, `Android`, or `Unknown`
`face2Meta`	string	No	Device type for `Face2`: `Desktop`, `Ios`, `Android`, or `Unknown`
`CRef`	string	No	Your transaction reference

Response

The response has the same fields as Face Compare, plus a liveness result for each image. Status reflects the face comparison only, so check LivenessPassResult in each liveness result.

{
  "VerifyResult": {
    "isIdentical": true,
    "confidence": 0.98
  },
  "face1LivenessResult": {
    "LivenessResultScore": 1,
    "LivenessResultProbability": 0.85,
    "LivenessResultQuality": 0.9,
    "LivenessResultClass": false,
    "LivenessPassResult": true,
    "LivenessMessage": "Liveness check successful"
  },
  "face2LivenessResult": {
    "LivenessResultScore": 1,
    "LivenessResultProbability": 0.85,
    "LivenessResultQuality": 0.9,
    "LivenessResultClass": false,
    "LivenessPassResult": true,
    "LivenessMessage": "Liveness check successful"
  },
  "trackingNumber": "00000000-0000-0000-0000-000000000000",
  "RequestedBy": "string",
  "AuthorizedBy": "string",
  "CRef": "REF00001",
  "Status": "Success",
  "Message": "string"
}

Liveness Result Fields

face1LivenessResult and face2LivenessResult share these fields. The LivenessResult object in other didx:verify responses uses the same fields.

Field	Description
`LivenessResultScore`	Raw, unbounded liveness score. Higher means more likely live. Use it for calibration, not for pass or fail decisions
`LivenessResultProbability`	Probability that the image is of a live person, from 0 to 1. A value above 0.5 usually indicates a live person
`LivenessResultQuality`	Quality of the image for liveness analysis, from 0 to 1. A value below 0.5 usually means the image is unsuitable
`LivenessResultClass`	Obsolete image-suitability class. Use `LivenessResultQuality` instead
`LivenessPassResult`	`true` if the liveness check passed
`LivenessMessage`	Human-readable result message

Use LivenessPassResult for the pass or fail decision. LivenessResultClass classifies whether the image is suitable for liveness analysis. It doesn’t indicate whether a spoof was detected.

Identity Verification

Biometrics

Compliance & Screening

Financial Verification

Enterprise

Face Compare

Overview

Face Compare

Request Fields

Response

Face Compare with Liveness

Request Fields

Response

Liveness Result Fields

​Overview

​Face Compare

​Request Fields

​Response

​Face Compare with Liveness

​Request Fields

​Response

​Liveness Result Fields

Overview

Face Compare

Request Fields

Response

Face Compare with Liveness

Request Fields

Response

Liveness Result Fields