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.
timeoutMs	int	No (default 5000)	Fail-fast budget in milliseconds. Exceeding it returns 504 Gateway Timeout. Clamped to 250–30000; zero or negative values fall back to the default. See below.

Fail-Fast Timeout

The whole call is bounded by timeoutMs (default 5000 ms). The budget starts once the request payload is on the server (upload time is excluded); if the comparison can't finish inside it, the call fails fast with 504 Gateway Timeout instead of blocking your integration. A 504 is safe to retry.

Images Without a Face

Each image must contain at least one detectable face. When one doesn't, the call returns 422 Unprocessable Entity with a problem detail naming the offending image — "First image could not find a face" or "Second image could not find a face". This is an input problem, not a server fault: retrying with the same images returns the same result. Fix the image (or pre-screen with faceDetect) before retrying.

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",
  "timeoutMs": 5000
}

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.
422 Unprocessable Entity	One of the images has no detectable face. Not retryable with the same images.
500 Internal Server Error	A server-side error occurred.
504 Gateway Timeout	The comparison did not complete within the timeoutMs budget. Safe to retry.

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.
• A 422 means an image has no detectable face — fix the input; a 504 means the timeoutMs budget was exceeded — retry, or raise the budget if your integration can tolerate the wait.
• To match a face against the enrolled gallery rather than a single other image, use faceDetect.