Compare Faces

faceCompare does a 1:1 comparison of two face images and tells you whether they are the same person, along with the raw confidence score. Unlike faceDetect, it doesn't touch the enrolled gallery — it only compares the two images you send.

API Endpoint

• HTTP Method: POST
• Endpoint: /api/v1/faces/faceCompare
• Base URL (Cloud): https://customername.econnectcloud.com/identities
• Base URL (On-prem): https://<server-host-or-ip>:5009

Authentication

Requires a JWT bearer token in the Authorization header. See Authentication.

Minimum Permission

The permission name and category below are what you'll see in the Identities web app under System → System settings → Roles.

Permission	Category
Face Detection	Facial Recognition Services

Request Body

Content-Type: application/json. Both images are sent as base64-encoded strings.

Field	Type	Required	Description
image1	byte[] (base64)	Yes	The first face image.
image2	byte[] (base64)	Yes	The second face image to compare against the first.

How match Is Decided

The comparison always returns a raw confidence. match is derived server-side: it is true when confidence meets the server's configured minimum match threshold, and false otherwise.

Apply your own threshold if you need one

Because the raw confidence is always returned, you can ignore match and apply a stricter threshold of your own for high-assurance flows — e.g. only accept a match at confidence >= 0.95 even if the server would call a lower score a match.

Code Examples

Curl

API_URL="https://customername.econnectcloud.com/identities"
TOKEN="your_jwt"          # from POST /api/v1/authenticate
IMG1_B64=$(base64 -w 0 face.jpg)
IMG2_B64=$(base64 -w 0 face2.jpg)

# Compare two faces (1:1). "match" is threshold-based; "confidence" is the raw score.
curl -sk -X POST "$API_URL/api/v1/faces/faceCompare" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d "{\"image1\": \"$IMG1_B64\", \"image2\": \"$IMG2_B64\"}" | jq

PowerShell

$API_URL = "https://customername.econnectcloud.com/identities"
$TOKEN   = "your_jwt"        # from POST /api/v1/authenticate
$headers = @{ Authorization = "Bearer $TOKEN" }
$img1B64 = [Convert]::ToBase64String([System.IO.File]::ReadAllBytes("face.jpg"))
$img2B64 = [Convert]::ToBase64String([System.IO.File]::ReadAllBytes("face2.jpg"))

# Compare two faces (1:1).
$compare = @{ image1 = $img1B64; image2 = $img2B64 } | ConvertTo-Json
Invoke-RestMethod -Uri "$API_URL/api/v1/faces/faceCompare" -Method Post `
    -Headers $headers -Body $compare -ContentType "application/json"

C#

using eConnect.IdentitiesDbSdk;

// NuGet: eConnect.IdentitiesDbSdk (private package - request access from eConnect support).

var httpClient = new HttpClient();

var sdk = await IdentityDbSdk.GetSdk(
    "https://customername.econnectcloud.com/identities",
    httpClient,
    "your_username",
    "your_password");

byte[] image1 = await File.ReadAllBytesAsync("face.jpg");
byte[] image2 = await File.ReadAllBytesAsync("face2.jpg");

// Compare two faces (1:1).
var cmp = await sdk.FaceCompareAsync(new FaceCompareRequest { Image1 = image1, Image2 = image2 });

// match is threshold-based; keep confidence if you want a stricter rule of your own.
Console.WriteLine($"match={cmp.Match} confidence={cmp.Confidence:P1}");

Raw Sample

Request

POST https://customername.econnectcloud.com/identities/api/v1/faces/faceCompare
Authorization: Bearer <your_jwt_token>
Content-Type: application/json

{
  "image1": "base64_encoded_first_face",
  "image2": "base64_encoded_second_face"
}

Response

200 OK — a FaceCompareResponse:

{ "match": true, "confidence": 0.97 }

Response Fields

Field	Type	Description
match	bool	true when confidence meets the server's minimum match threshold.
confidence	float	Raw similarity score, 0.0–1.0.

Response Codes

Code	Meaning
200 OK	The comparison ran; match and confidence are returned.
401 Unauthorized	Missing or invalid JWT.
403 Forbidden	The user lacks the Face Detection permission.
500 Internal Server Error	A server-side error occurred (e.g. a face could not be found in one of the images).

Notes

• match is threshold-based on the server's configured minimum; confidence is the raw score.
• Keep the raw confidence if you want to apply a stricter, integration-specific threshold.
• To match a face against the enrolled gallery rather than a single other image, use faceDetect.