Lookup

lookup matches a face against enrolled identities using a multipart/form-data upload — send the cropped/aligned face (and optionally precomputed embeddings) as files rather than base64 JSON. It returns the matched person, if any.

API Endpoint

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

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

A multipart/form-data upload. The form fields are eConnect edge-model inputs — see Advanced below.

Code Examples

Curl

API_URL="https://customername.econnectcloud.com/identities"
TOKEN="your_jwt"

# multipart/form-data upload - send the files directly (no base64 needed).
curl -sk -X POST "$API_URL/api/v1/faceEdge/lookup" \
  -H "Authorization: Bearer $TOKEN" \
  -F "CroppedAligned=@cropped-aligned.jpg" \
  -F "Embeddings=@embeddings.bin" \
  -F "RecognitionModel=arcface" | jq

PowerShell

$API_URL = "https://customername.econnectcloud.com/identities"
$TOKEN   = "your_jwt"

$form = @{
    CroppedAligned   = Get-Item -Path "cropped-aligned.jpg"
    Embeddings       = Get-Item -Path "embeddings.bin"
    RecognitionModel = "arcface"
}

$person = Invoke-RestMethod -Uri "$API_URL/api/v1/faceEdge/lookup" `
    -Method Post `
    -Headers @{ Authorization = "Bearer $TOKEN" } `
    -Form $form

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

// lookup uploads the cropped/aligned face (and optionally precomputed embeddings)
// as multipart/form-data. The SDK wraps the files in FileParameter for you.
await using var croppedStream = File.OpenRead("cropped-aligned.jpg");
await using var embeddingsStream = File.OpenRead("embeddings.bin");

EdgePerson person = await sdk.FaceEdgeLookupAsync(
    croppedAligned: new FileParameter(croppedStream, "cropped-aligned.jpg", "application/octet-stream"),
    embeddings:     new FileParameter(embeddingsStream, "embeddings.bin", "application/octet-stream"),
    recognitionModel: "arcface");

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

Response

200 OK — an EdgePerson (same shape as recognize):

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

Response Codes

Code	Meaning
200 OK	A match was found; the EdgePerson is returned.
404 Not Found	No face found in the image, or no person matched.
401 Unauthorized	Missing or invalid JWT.
403 Forbidden	The user lacks the Face Recognize permission.

Advanced

eConnect edge-model inputs (multipart/form-data)

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	file	Yes	The cropped/aligned face image to match.
Embeddings	file	No	Precomputed embeddings as a binary blob.
RecognitionModel	text	No	Recognition model name.