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 Not Authorized 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}
  • 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.

Request Body​

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

Required Fields​

  • personPhoto: Base64-encoded image of the person’s face. This photo must only contain one face, and it should be of high quality for successful enrollment.

Optional Fields​

  • firstName: First name of the person being enrolled (optional).
  • middleName: Middle name of the person (optional).
  • lastName: Last name of the person (optional).
  • monitorReason: Reason for enrolling the individual in monitoring (optional).
  • tags: An array of tags that describe the individual (e.g., "Banned", "VIP", etc.) (optional).
  • additionalFields: Any additional information, such as TenantID, that needs to be stored with the person’s data (optional).

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",
  "lastName": "Doe",
  "monitorReason": "VIP Monitoring",
  "tags": ["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).
  • 500 Internal Server Error: An issue occurred on the server side.
  • 401 Unauthorized: Missing or invalid JWT token.

Example Response

{
  
}

Additional Notes​

  • Ensure the externalId provided in the URL matches the one used in your system to identify the individual uniquely.
  • 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.
  • Optionally, you can pass additional tags or fields to categorize the individual or store extra information.