Check Image Reference

checkImageReference tells you whether a face image you previously enrolled under a caller-supplied photoReferenceId is already in the system. It is the safe-retry companion to faceEnroll: check before re-sending so a retried enrollment doesn't duplicate a face.

API Endpoint

• HTTP Method: GET
• Endpoint: /api/v1/faces/checkImageReference/{referenceId}
• 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

Path Parameters

Parameter	Type	Description
referenceId	string	The photoReferenceId you passed to faceEnroll.

Code Examples

Curl

API_URL="https://customername.econnectcloud.com/identities"
TOKEN="your_jwt"          # from POST /api/v1/authenticate

# Check whether a photoReferenceId has already been enrolled.
# referenceId is the same value you passed as photoReferenceId to faceEnroll.
curl -sk -X GET "$API_URL/api/v1/faces/checkImageReference/ext-123" \
  -H "Authorization: Bearer $TOKEN" | jq

# Typical retry flow: if exists=false, call faceEnroll with that photoReferenceId;
# if exists=true, the face is already enrolled - skip the enrollment.

PowerShell

$API_URL = "https://customername.econnectcloud.com/identities"
$TOKEN   = "your_jwt"        # from POST /api/v1/authenticate
$headers = @{ Authorization = "Bearer $TOKEN" }

# Check whether a photoReferenceId has already been enrolled.
$check = Invoke-RestMethod -Uri "$API_URL/api/v1/faces/checkImageReference/ext-123" `
    -Method Get -Headers $headers

if ($check.exists) { "Already enrolled as faceId $($check.faceId)" }
else               { "Not enrolled - safe to call faceEnroll" }

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

// Check whether a reference has already been enrolled (the safe-retry companion to faceEnroll).
var check = await sdk.CheckImageReferenceAsync("ext-123");

if (check.Exists)
    Console.WriteLine($"Already enrolled as faceId {check.FaceId}");
else
    Console.WriteLine("Not enrolled - safe to call FaceEnrollAsync with this photoReferenceId");

Raw Sample

Request

GET https://customername.econnectcloud.com/identities/api/v1/faces/checkImageReference/ext-123
Authorization: Bearer <your_jwt_token>

Response

200 OK — an ImageReferenceCheckResult:

{
  "exists": true,
  "faceId": "5f9c2b7a-3e41-4d8a-9b6c-1a2b3c4d5e6f",
  "detectId": "c1d2e3f4-a5b6-7c8d-9e0f-1a2b3c4d5e6f"
}

When the reference has not been enrolled, exists is false and faceId / detectId are null:

{ "exists": false, "faceId": null, "detectId": null }

Response Fields

Field	Type	Description
exists	bool	true when a face has been enrolled under this referenceId.
faceId	string	The enrolled face's identifier. null when exists is false.
detectId	string	The detection identifier for that enrollment. null when exists is false.

Response Codes

Code	Meaning
200 OK	The check ran; exists reports the result.
401 Unauthorized	Missing or invalid JWT.
403 Forbidden	The user lacks the Face Detection permission.
500 Internal Server Error	A server-side error occurred.

Notes

• A missing reference is not a 404 — it returns 200 OK with exists: false.
• Use the same referenceId you supplied as photoReferenceId on faceEnroll.
• Typical flow: checkImageReference → if exists: false, call faceEnroll with that photoReferenceId; if exists: true, skip the enrollment.