Recognize

recognize matches a cropped/aligned face (sent as JSON) against the enrolled identities and returns the matched person, if any.

API Endpoint

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

Authentication

Requires a JWT bearer token. 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 Recognize	Facial Recognition Services

Request Body

Content-Type: application/json.

Field	Type	Required	Description
detectorName	string	Yes	Identifier of the detector/source.
ianaTimeZone	string	Yes	IANA time zone of the detection.
detectTimeUtc	string (ISO-8601 UTC)	Yes	UTC timestamp of the detection.

The face input itself (croppedAligned) and the related model fields are eConnect edge-model inputs — see Advanced below.

Code Examples

Curl

API_URL="https://customername.econnectcloud.com/identities"
TOKEN="your_jwt"
CROPPED_FILE="cropped-aligned.jpg"

CROPPED_B64=$(base64 -w 0 "$CROPPED_FILE")

REQUEST=$(cat <<EOF
{
  "croppedAligned": "$CROPPED_B64",
  "detectorName": "FrontDoorCam",
  "ianaTimeZone": "America/Los_Angeles",
  "detectTimeUtc": "$(date -u +%Y-%m-%dT%H:%M:%SZ)"
}
EOF
)

curl -sk -X POST "$API_URL/api/v1/faceEdge/recognize" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d "$REQUEST" | jq

PowerShell

$API_URL      = "https://customername.econnectcloud.com/identities"
$TOKEN        = "your_jwt"
$CROPPED_FILE = "cropped-aligned.jpg"

$croppedB64 = [Convert]::ToBase64String([System.IO.File]::ReadAllBytes($CROPPED_FILE))

$body = @{
    croppedAligned = $croppedB64
    detectorName   = "FrontDoorCam"
    ianaTimeZone   = "America/Los_Angeles"
    detectTimeUtc  = (Get-Date).ToUniversalTime().ToString("yyyy-MM-ddTHH:mm:ssZ")
} | ConvertTo-Json

$person = Invoke-RestMethod -Uri "$API_URL/api/v1/faceEdge/recognize" `
    -Method Post `
    -Headers @{ Authorization = "Bearer $TOKEN" } `
    -Body $body -ContentType "application/json"

$person

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");

// recognize matches a cropped/aligned face against enrolled identities.
byte[] croppedAligned = await File.ReadAllBytesAsync("cropped-aligned.jpg");

EdgePerson person = await sdk.FaceEdgeRecognizeLookupAsync(new FaceEdgeRecognize
{
    CroppedAligned = croppedAligned,        // required for recognize
    DetectorName   = "FrontDoorCam",        // required
    IanaTimeZone   = "America/Los_Angeles", // required
    DetectTimeUtc  = DateTime.UtcNow        // required
    // RecognitionModel / Embeddings are optional
});

if (person != null)
{
    Console.WriteLine($"Matched {person.FirstName} {person.LastName} " +
                      $"(PersonId={person.PersonId}, FaceId={person.FaceId})");
}

Response

200 OK — an EdgePerson for the matched identity:

{
  "faceId": "5f9c2b7a-3e41-4d8a-9b6c-1a2b3c4d5e6f",
  "personId": "0a1b2c3d-4e5f-6a7b-8c9d-0e1f2a3b4c5d",
  "firstName": "Jane",
  "lastName": "Doe",
  "tags": [{ "name": "VIP" }]
}

Response Fields

Field	Type	Description
faceId	string	The matched face's identifier.
personId	string (GUID)	The matched person's identifier.
firstName / lastName	string	The person's primary alias.
tags[]	array	Tags applied to the person ({ "name": "..." }).

Response Codes

Code	Meaning
200 OK	A match was found; the EdgePerson is returned.
400 Bad Request	Invalid request, no face found, or no person matched.
401 Unauthorized	Missing or invalid JWT.
403 Forbidden	The user lacks the Face Recognize permission.

Have files instead of base64?

Use lookup to upload the face and embeddings as multipart/form-data.

Advanced

eConnect edge-model inputs

These inputs are highly proprietary and produced by eConnect's own edge models. This endpoint is intended for eConnect edge deployments rather than general partner integrations.

Field	Type	Required	Description
croppedAligned	byte[] (base64)	Yes	The cropped/aligned face image to match (an eConnect edge-model output).
embeddings	float[]	No	Precomputed embeddings.
recognitionModel	string	No	Recognition model name.