Face Recognition

The Face Recognition endpoints work directly with face images: enroll a face for a person, detect faces in an image, compare two faces, and check whether an enrollment image reference already exists.

Enrollment is how identities get faces

faceEnroll is the REST entry point for creating a person from a face (or attaching another photo to an existing person). Use it together with Person Management to fill in names, tags, and attributes.

API Endpoints

Base URL (Cloud): https://customername.econnectcloud.com/identities
Base URL (On-prem): https://<server-host-or-ip>:5009

Method	Endpoint	Description	Permission
`POST`	`/api/v1/faces/faceEnroll`	Enroll a face — create a person or add a photo to one.	Face Enrollment
`POST`	`/api/v1/faces/faceDetect`	Detect faces in an image.	Face Detection
`POST`	`/api/v1/faces/faceCompare`	Compare two faces (1:1).	Face Detection
`GET`	`/api/v1/faces/checkImageReference/{referenceId}`	Check whether an enrollment image reference exists.	Face Detection

Authentication

Requires a JWT bearer token. See Authentication.

Permissions

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

Operation	Permission	Category
`faceEnroll`	Face Enrollment	Facial Recognition Services
`faceDetect` / `faceCompare` / `checkImageReference`	Face Detection	Facial Recognition Services

Code Examples

Curl
PowerShell
C#

API_URL="https://customername.econnectcloud.com/identities"
TOKEN="your_jwt"
IMG_B64=$(base64 -w 0 face.jpg)

# Enroll a face - creates a NEW person and returns its personId
curl -sk -X POST "$API_URL/api/v1/faces/faceEnroll" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d "{\"faceImage\": \"$IMG_B64\", \"photoReferenceId\": \"ext-123\"}" | jq
# Add a face to an EXISTING person instead:
#   POST "$API_URL/api/v1/faces/faceEnroll?personId=<personId>&forceEnrollment=false"

# Detect faces in an image
curl -sk -X POST "$API_URL/api/v1/faces/faceDetect" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d "{\"image\": \"$IMG_B64\"}" | jq

# Compare two faces (1:1)
IMG2_B64=$(base64 -w 0 face2.jpg)
curl -sk -X POST "$API_URL/api/v1/faces/faceCompare" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d "{\"image1\": \"$IMG_B64\", \"image2\": \"$IMG2_B64\"}" | jq

# Check whether an enrollment image reference already exists
curl -sk -X GET "$API_URL/api/v1/faces/checkImageReference/ext-123" \
  -H "Authorization: Bearer $TOKEN" | jq

$API_URL = "https://customername.econnectcloud.com/identities"
$TOKEN   = "your_jwt"
$headers = @{ Authorization = "Bearer $TOKEN" }
$imgB64  = [Convert]::ToBase64String([System.IO.File]::ReadAllBytes("face.jpg"))

# Enroll a face - creates a NEW person and returns its personId
$enroll = @{ faceImage = $imgB64; photoReferenceId = "ext-123" } | ConvertTo-Json
Invoke-RestMethod -Uri "$API_URL/api/v1/faces/faceEnroll" -Method Post `
    -Headers $headers -Body $enroll -ContentType "application/json"
# Add to an existing person: append ?personId=<personId> to the URL

# Detect faces in an image
$detect = @{ image = $imgB64 } | ConvertTo-Json
Invoke-RestMethod -Uri "$API_URL/api/v1/faces/faceDetect" -Method Post `
    -Headers $headers -Body $detect -ContentType "application/json"

# Compare two faces (1:1)
$img2B64 = [Convert]::ToBase64String([System.IO.File]::ReadAllBytes("face2.jpg"))
$compare = @{ image1 = $imgB64; image2 = $img2B64 } | ConvertTo-Json
Invoke-RestMethod -Uri "$API_URL/api/v1/faces/faceCompare" -Method Post `
    -Headers $headers -Body $compare -ContentType "application/json"

# Check an enrollment image reference
Invoke-RestMethod -Uri "$API_URL/api/v1/faces/checkImageReference/ext-123" -Method Get -Headers $headers

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[] image = await File.ReadAllBytesAsync("face.jpg");

// Enroll a face - creates a new person (omit personId) and returns its personId
var enroll = await sdk.FaceEnrollAsync(body: new FaceEnrollRequest
{
    FaceImage        = image,
    PhotoReferenceId = "ext-123"
});
Console.WriteLine($"Enrolled person: {enroll.PersonId}");

// Add a face to an existing person:
// await sdk.FaceEnrollAsync(personId: existingId, forceEnrollment: false,
//     body: new FaceEnrollRequest { FaceImage = image });

// Detect faces in an image
var detected = await sdk.FaceDetectAsync(new FaceDetectRequest { Image = image });
foreach (var f in detected.Detections)
    Console.WriteLine($"faceId={f.FaceId} quality={f.Quality:P1}");

// Compare two faces (1:1)
byte[] image2 = await File.ReadAllBytesAsync("face2.jpg");
var cmp = await sdk.FaceCompareAsync(new FaceCompareRequest { Image1 = image, Image2 = image2 });
Console.WriteLine($"match={cmp.Match} confidence={cmp.Confidence:P1}");

// Check whether an enrollment image reference exists
var check = await sdk.CheckImageReferenceAsync("ext-123");
Console.WriteLine($"exists={check.Exists}");

Enroll a Face

Method / Path: POST /api/v1/faces/faceEnroll
Query parameters:
- personId (optional, GUID) — attach the face to this existing person. Omit to create a new person.
- forceEnrollment (optional, bool, default false) — enroll even if quality checks would normally reject the image.

Request Body

Field	Type	Description
`faceImage`	`byte[]` (base64)	The face image to enroll.
`photoReferenceId`	`string`	Optional caller-supplied reference id for the image (used by `checkImageReference`).

Response

{ "personId": "0a1b2c3d-4e5f-6a7b-8c9d-0e1f2a3b4c5d" }

When no personId is supplied a new person is created and returned; if enrollment fails, that just-created person is rolled back automatically.

Detect Faces

Method / Path: POST /api/v1/faces/faceDetect
Body: { "image": "<base64>" }

{
  "detections": [
    {
      "faceId": "5f9c2b7a-3e41-4d8a-9b6c-1a2b3c4d5e6f",
      "personId": "0a1b2c3d-4e5f-6a7b-8c9d-0e1f2a3b4c5d",
      "confidence": 0.981,
      "quality": 0.93,
      "boundingBox": { "x": 320, "y": 145, "width": 96, "height": 96 }
    }
  ]
}

personId is null when the detected face doesn't match a known person.

Compare Faces

Method / Path: POST /api/v1/faces/faceCompare
Body: { "image1": "<base64>", "image2": "<base64>" }

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

Check Image Reference

Method / Path: GET /api/v1/faces/checkImageReference/{referenceId}

{ "exists": true, "faceId": "5f9c2b7a-...", "detectId": "c1d2e3f4-..." }

Response Codes

Code	Meaning
`200 OK`	The operation succeeded.
`404 Not Found`	(faceEnroll) the supplied `personId` was not found.
`401 Unauthorized`	Missing or invalid JWT.
`403 Forbidden`	The user lacks the required Facial Recognition Services permission.
`500 Internal Server Error`	A server-side error occurred (e.g. image rejected).

API Endpoints​

Authentication​

Permissions​

Code Examples​

Enroll a Face​

Request Body​

Response​

Detect Faces​

Compare Faces​

Check Image Reference​

Response Codes​