Skip to main content

Monitoring Faces

When enrolling faces into the Events Bridge system, there are several important considerations to ensure successful enrollment and accurate monitoring. Below are key guidelines for using the face monitoring services effectively:

  1. Unique ID Requirement Each enrollment must include an ID that is unique to the partner's system. This externalId is how Events Bridge tracks the photos and faces associated with each partner. This ID is stored in the eConnect system and is required for future reference and monitoring of the specific face.

  2. Photo Quality and Face Visibility

    • Quality of Photos: Photos must be of decent quality for successful enrollment. The system may reject images if the face is blurry, unfocused, or obscured in any way. The best results come from clear, forward-facing images with no obstructions (e.g., glasses, hats, or masks).
    • One Face Per Photo: Each photo must contain only one face to ensure accurate monitoring. If multiple faces are present in a photo, clear out or black out the additional faces before submitting the image. Failure to do so may result in rejection or incorrect enrollment.
    • Handling Rejections: While eConnect will attempt to enroll any provided image, it reserves the right to reject images that do not meet quality standards, providing a reason for the rejection.

  3. Authenticated API Calls This service requires authentication via a JWT Bearer token. Make sure to include the JWT Auth Bearer token in the header of your API requests. Without this token, the system will respond with a 401 Unauthorized error.

  4. Optional Tags and Categories You can optionally supply a Tag or Category for the person being enrolled. Tags could include identifiers such as "Banned", "Advantage Player", "Employee", "VIP", or any other relevant label that fits your system's use case. These tags help categorize and manage monitored individuals.

  5. Additional Data If there is extra information you need to be passed back during callbacks (e.g., TenantId), you can supply it in the additionalFields parameter during the enrollment process. This data will be stored and included in future detections.

API Endpoint​

  • HTTP Method: PUT
  • Endpoint: /api/v1/faces/monitor/{externalId}
  • Private Server Base URL: https://10.0.0.123:5022
  • Cloud Server Base URL: https://customername.econnectcloud.com/eventsbridge

Authentication​

This API call requires authentication with a JWT token, which must be passed in the header of the request.

Path Parameter​

  • externalId: The unique ID assigned by the partner's system to identify the person being enrolled. This ID must be unique to the partner and is required for tracking and future interactions. It is case sensitive.

Request Body​

The PUT request requires the following data to be passed in the body of the request.

Required Fields​

  • personPhoto (String): The person's face photo, base64-encoded. The underlying field is a byte array, so JSON callers send it as a base64 string. This photo must contain exactly one face and should be of high quality for successful enrollment.

Optional Fields​

  • firstName (String): First name of the person being enrolled.
  • middleName (String): Middle name of the person.
  • lastName (String): Last name of the person.
  • monitorReason (String): Reason for enrolling the individual in monitoring. This is human-readable text that is written to the eConnect notes for the subject, and it comes back in the notes array of a Face WebHook payload.
  • tags (Array of Objects): Tags that describe the individual, each with a single tagName property.
    • Tags are prefixed with the field prefix assigned to your account. If your account is SystemA and you send the tag Banned, it is stored in eConnect as SystemA-Banned.
    • If you supply no tags, one is added automatically using your field prefix as the tag name. This is what stops the subject being removed by routine cleanup processes.
  • additionalFields (Array of Objects): Any additional information, such as a TenantId, to store with the person's data. Each entry has a fieldName and a fieldValue, and the whole array is replayed back to you in the fields property of every detection webhook.

Code Examples​

using eConnect.EventsBridge.Sdk;

// Assuming sdk is already initialized with authentication
// Define the externalId
string externalId = "12345";

// Check if already enrolled
var status = await sdk.FaceMonitorStatusCheckAsync(externalId);
if (status.Enrolled)
{
    await sdk.FaceUnMonitorAsync(externalId);
}

// Read the photo
byte[] personPhoto = System.IO.File.ReadAllBytes("photo.jpg");

// Create the FaceMonitorRequest
var request = new FaceMonitorRequest
{
    PersonPhoto = personPhoto,
    FirstName = "John",
    LastName = "Doe",
    MonitorReason = "Example",
    Tags = new List<TagInfoItem> { new TagInfoItem { TagName = "VIP" } },
    AdditionalFields = new List<AdditionalFieldItem> { new AdditionalFieldItem { FieldName = "Note", FieldValue = "Important person" } }
};

// Monitor the face
await sdk.FaceMonitorAsync(externalId, request);

Raw Sample​

Here's an example of how to use the PUT method to enroll a face:

Request​

PUT https://10.0.0.123:5022/api/v1/faces/monitor/12345
Authorization: Bearer <your_jwt_token>
Content-Type: application/json
{
  "personPhoto": "base64_encoded_image_data",
  "firstName": "John",
  "middleName": "Michael",
  "lastName": "Doe",
  "monitorReason": "VIP Monitoring",
  "tags": [{ "tagName": "VIP" }],
  "additionalFields": [
    {
      "fieldName": "TenantID",
      "fieldValue": "123ABC"
    }
  ]
}

Response​

  • 200 OK: The face was successfully enrolled and is now being monitored.
  • 400 Bad Request: There was an issue with the provided data (e.g., invalid image or missing required fields).
  • 401 Unauthorized: Missing or invalid JWT token.
  • 500 Internal Server Error: An issue occurred on the server side, such as the image being rejected for quality. The reason is returned in the problem details body.

Example Response​

{}

The success response body is an empty object by design — FaceMonitorResponse carries no fields. Treat the 200 status code as the result, and do not expect any properties to read.

Additional Notes​

  • Ensure the externalId provided in the URL matches the one used in your system to identify the individual uniquely. It is case sensitive.
  • The personPhoto must be a clear, high-quality image containing only one face for accurate monitoring. The system will reject blurry or low-quality images.
  • This endpoint both creates and updates. Sending a second PUT for an externalId you already enrolled replaces the stored record rather than creating a duplicate.
  • Enrollment is not necessarily instant across every connected server. Use Get All Monitored to confirm the subject reached all of them.
Last updated on by Travis Whidden