Face Comparison

Compare two face images to determine whether they belong to the same person.

POST /api/onboarding/biometrics/face/comparison

Face Comparison

cURL

curl --request POST \
  --url https://adhere-api.smartcomply.com/api/onboarding/biometrics/face/comparison \
  --header 'Content-Type: application/json' \
  --header 'x-access-token: <api-key>' \
  --data '
{
  "image_url": "<string>",
  "selfie_url": "<string>"
}
'

200

facesMatch

{
  "status": "success",
  "data": {
    "status": true,
    "response_code": "00",
    "message": "Face Match",
    "confidence": 100,
    "record_id": 76981
  },
  "message": "Face comparison completed successfully"
}

The Face Comparison endpoint uses biometric analysis to compare two face images and returns a confidence score indicating whether they depict the same individual. Use this for identity verification during onboarding or transaction approval.

Before comparing, the provider runs an anti-spoofing check on selfie_url; if that check fails, no comparison is attempted and the response says so explicitly — see 200 OK — rejected by anti-spoofing check below.

Endpoint

POST /api/onboarding/biometrics/face/comparison

Request

Headers

Header	Value	Required
x-access-token	Your API secret key	Yes
Content-Type	application/json	Yes

Body Parameters

Parameter	Type	Required	Description
image_url	string	Yes	URL of the reference ID photo or database face image
selfie_url	string	Yes	URL of the live selfie to compare against the reference

Example

cURL

curl -X POST "https://adhere-api.smartcomply.com/api/onboarding/biometrics/face/comparison" \
  -H "x-access-token: YOUR_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "image_url": "https://example.com/id_photo.jpg",
    "selfie_url": "https://example.com/selfie.jpg"
  }'

Response

200 OK

Field	Type	Description
data.status	boolean	true if the faces match, false if they do not
data.response_code	string	"00" indicates a successful comparison
data.message	string	Human-readable match result
data.confidence	integer	Match confidence percentage (0–100)
data.record_id	number	Internal record ID for this check

{
  "status": "success",
  "data": {
    "status": true,
    "response_code": "00",
    "message": "Face Match",
    "confidence": 100,
    "record_id": 76981
  },
  "message": "Face comparison completed successfully"
}

A data.status of false indicates the faces do not match. Use data.confidence to apply your own threshold for acceptance (e.g., require >= 80 for a positive match).

200 OK — rejected by anti-spoofing check (no comparison performed)

Before comparing the two images, the provider runs its own anti-spoofing check on selfie_url — this catches a photo of a photo, a screen replay, or another spoofed submission. If selfie_url fails that check, the comparison itself never runs, and the response explains why in data.message rather than simply saying the faces don’t match. data.confidence is 0 in this case since no match score was produced.

This check runs even though selfie_url is a still image, not a video — the message text below still refers to “the submitted video” because it’s shared with the Face Liveness Check endpoint’s internal wording. Treat this response the same way regardless of whether you submitted a photo or a video as the selfie.

{
  "status": "failed",
  "data": {
    "status": false,
    "response_code": "01",
    "message": "Liveness check failed — the submitted video did not pass the liveness/anti-spoofing check, so no face comparison was performed.",
    "confidence": 0
  },
  "message": "Liveness check failed — the submitted video did not pass the liveness/anti-spoofing check, so no face comparison was performed."
}

Ask the user for a clearer selfie (better lighting, no screen/photo in frame) and resubmit — this is not the same failure as a genuine face mismatch, and retrying with a better-quality selfie of the same person is the correct next step.

400 Bad Request

Returned when one or both image URLs are missing, inaccessible, or do not contain a detectable face.

{
  "status": "failed",
  "data": [],
  "message": "Could not process one or both images"
}

401 Unauthorized

{
  "status": "failed",
  "message": "Authentication credentials were not provided."
}

Authorizations

x-access-token · string · header · required

Your Adhere API secret key

Body

application/json

image_url · string · required

URL of the reference ID photo

selfie_url · string · required

URL of the selfie image

Response

200

application/json

Comparison ran to completion. This includes the anti-spoofing rejection case below — the provider still returns HTTP 200 with status "failed" when selfie_url fails its own liveness check before any comparison is attempted.