Integration with AWS Rekognition

For security reasons we do not store face collections on the VMS. We instead manage face collections using a web application stack.

This article outlines the steps used to integrate the stack with AWS Rekognition to manage a face collection and the VMS backend to create alerts.

Managing a FaceCollection

Amazon Rekognition API References

How do we manage the AWS Face Collection?

• Cloud Two creates one AWS Rekognition Face Collection per customer company.

• The collection ID (externalFaceCollectionId) is generated automatically using the company name and ID.

• The collection is created:

  • during deployment (migrations) for existing companies,

  • automatically when a new customer company is created.

• Customers do not need to create or manage AWS collections themselves.

• https://docs.aws.amazon.com/rekognition/latest/APIReference/API_CreateCollection.html

Creating users and associating faces

• When a person is created in Cloud Two, we also create a User in AWS Rekognition.

• This AWS User ID is stored as externalId.

• When face images are uploaded:

  • images are stored in S3,

  • faces are indexed in the AWS collection,

  • each face is associated with the corresponding AWS User.

• Multiple images can be associated with the same user to improve recognition accuracy.

• https://docs.aws.amazon.com/rekognition/latest/APIReference/API_CreateUser.html

• https://docs.aws.amazon.com/rekognition/latest/APIReference/API_IndexFaces.html

• https://docs.aws.amazon.com/rekognition/latest/APIReference/API_AssociateFaces.html

How is this information stored in the Cloud Two backend?

Cloud Two keeps a clear separation between people and face images:

Face (Person)

• Represents a real person (name, contact info, sites).

• Stored once per person.

• Contains externalId, which is the AWS Rekognition User ID.

Face Collection (Images)

• Stores individual face images linked to a person.

• Contains:

  • S3 file reference,

  • AWS FaceId (result of face indexing),

  • association status.

• Multiple images can belong to the same person.

Using the FaceCollection in the VMS

How do we create an Alert Rule using a User from the Face Collection?

• When creating an Alert Rule for Known People, the client selects one or more people from the Cloud Two Face list.

• The Alert Rule does not reference internal database IDs.

• Instead, it uses:

  • the company’s AWS Face Collection ID,

  • a list of AWS User IDs (Face.externalId) for the selected people.

These values are sent as metadata when the alert rule is created and are later used by the AI pipeline to match detected faces against the correct users.

API Request Example

We create the Alert Rule using the API call POST api/v3/alert_rules/.

Example request data:

{
      "alert_type": "human",
      "camera_ids": [
        849
      ],
      "created_at": "2026-01-07T14:58:44.282822",
      "event_aliases": [
        "motion"
      ],
      "id": 140,
      "meta": {
        "CloudMeta": "true",
        "FacialRecognition": "AWS",
        "face_collection": "Migration_Script_8a0fa252-6c4a-4ec0-abf0-8ecee84e1376",
        "indexes": "0f3a39c3-fd13-441a-bccf-73a54ca9736f"
      },
      "name": "Face Test",
      "recipients": {
        "app": [],
        "email": [],
        "sms": []
      },
      "schedule": {
        "friday": [
          {
            "start": "00:00",
            "stop": "23:59"
          }
        ],
        "monday": [
          {
            "start": "00:00",
            "stop": "23:59"
          }
        ],
        "saturday": [
          {
            "start": "00:00",
            "stop": "23:59"
          }
        ],
        "sunday": [
          {
            "start": "00:00",
            "stop": "23:59"
          }
        ],
        "thursday": [
          {
            "start": "00:00",
            "stop": "23:59"
          }
        ],
        "tuesday": [
          {
            "start": "00:00",
            "stop": "23:59"
          }
        ],
        "wednesday": [
          {
            "start": "00:00",
            "stop": "23:59"
          }
        ]
      },
      "site_ids": [],
      "topic": "arn:aws:sns:us-east-1:434114592570:vxg-dev-alert-rule-140"
}

The important information is this meta field:

"meta": {
    "CloudMeta": "true",
    "FacialRecognition": "AWS",
    "face_collection": "Migration_Script_8a0fa252-6c4a-4ec0-abf0-8ecee84e1376",
    "indexes": "0f3a39c3-fd13-441a-bccf-73a54ca9736f"
}

Where Migration_Script_8a0fa252-6c4a-4ec0-abf0-8ecee84e1376 is the face collection in AWS and 0f3a39c3-fd13-441a-bccf-73a54ca9736f is the unique UserId from the FaceCollection in AWS.