Watchlists

A watchlist is a named list of people, the watchlist members, that detected faces are matched against. A member can belong to several watchlists. A watchlist can be anything from a handful of VIPs to a nationwide register: employees, event attendees, students, or a block list. You can keep everyone in one watchlist or partition them (per department, per class, per site); each watchlist carries its own matching threshold and colour, so partitioning is also how you give different groups different strictness.

Members are managed in Station (see Manage watchlists) or through the REST API. In a multi-site deployment members are managed on the Leader only, see Deployment topologies.

Inputs

Enrollment and search accept a face image in one of these formats: BMP (.bmp, .dib), JPEG (.jpeg, .jpg, .jpe), JPEG 2000 (.jp2), PNG, WebP, portable image formats (.pbm, .pgm, .ppm, .pxm, .pnm) and TIFF (.tiff, .tif). Images are passed base64-encoded in the request body or, for enrollment, as a URI that the API downloads (ImageDownload__AllowedHosts restricts the hosts; downloads are capped at 10 MB and 10 s each). One registration may contain up to 50 images (WatchlistMemberRegistration__MaxImages). What makes a good enrollment image is covered in Enrollment image quality.

Enrollment via API

Adding a person to a watchlist is called enrollment (or registration). The minimum request to POST /api/v1/WatchlistMembers/Register:

{
  "id": "someUniqueId",
  "images": [{ "data": "/9j/4AAQ...f/9k=" }],
  "watchlistIds": ["060f1083-6610-4116-9082-d8e26596a115"],
  "fullName": "John Smith"
}

Property	Type	Description
id	string	Unique member identifier. Use an ID from your own system or a generated UUID; leave it out to let Face Matcher generate one.
images	array	Images to enroll for this member; each has a base64 data (or a URI). A template is extracted from every image.
watchlistIds	array	Watchlists the member is added to; at least one.
fullName	string	Legal or display name, up to 200 characters. Optional; may be anonymised.

Names, labels and IDs are not needed for identification and can be omitted or anonymised for privacy, see Data and privacy. The complete request, including labels and display name, is in the REST API reference; a worked example is in Enroll and identify.

Face validation at enrollment

Every image submitted for enrollment is checked against face validation limits before a template is stored, so that poor references do not degrade matching later. Validation is enabled by default; the defaults in .env of the release package are:

Setting	Default	Meaning
FaceValidation__Size__Min / Max	30 / —	Face size in pixels.
FaceValidation__AreaOnFrame__Min / Max	— / —	Face area relative to the image.
FaceValidation__TemplateQuality__Min / Max	10 / —	Template quality reported by the extractor; higher is better.
FaceValidation__FaceQuality__Min / Max	1000 / 10000	Detection quality reported by the detector.
FaceValidation__YawAngle__Min / Max	-20 / 20	Head rotation left/right.
FaceValidation__PitchAngle__Min / Max	-20 / 20	Head rotation up/down.
FaceValidation__RollAngle__Min / Max	-20 / 20	Head tilt.
FaceValidation__Brightness__Min / Max	— / —	Exposure of the face area.
FaceValidation__Sharpness__Min / Max	— / —	Sharpness of the face area.

An empty value means no limit. The endpoints POST /api/v1/WatchlistMembers/Register and POST /api/v1/WatchlistMembers/{id}/AddNewFace apply the predefined set by default; POST /api/v1/Watchlists/Search defaults to none. Pass faceValidation: "none" in a request to skip validation for that call.

Search via API

Searching a watchlist with a picture is identification (1:N): you send an image with one or more faces and get back the best-matching members. The minimum request to POST /api/v1/Watchlists/Search, searching all watchlists at threshold 50 for the single best candidate:

{
  "image": { "data": "/9j/4AAQ...f/9k=" },
  "threshold": 50,
  "maxResultCount": 1
}

Property	Type	Description
image	object	Image with one or more faces, base64 in data.
threshold	number	Matching threshold for this search, 0 – 100; scores below it are not returned.
maxResultCount	number	Maximum number of candidates per face.

Liveness can be added to the search with the spoofCheckConfig described in Liveness. Station exposes the same search as Identify a face. Searching past detections rather than watchlists is a different feature, see Face search.

Watchlist autolearn

Autolearn raises identification accuracy for people who pass the cameras regularly, typically in access control. Once a day it picks, for every member matched that day, the best face image from the matches and adds it to the member as an extra reference. Over the collection period (default 30 days) the oldest autolearn face is replaced, so members accumulate up to MaxAutoLearnFacesCount recent images that track their current appearance (glasses, beard, hair). Only matches at or above the selection threshold are used; set it higher than your matching threshold, or a stranger's face could be added to a member (watchlist poisoning).

Selected faces are kept in two clusters, no mask and face mask, so that masked and unmasked references do not dilute each other; this needs face mask detection, which is on by default. Faces whose FaceMaskConfidence lies between the two mask thresholds are not used.

Autolearn is off by default and configured with PUT /api/v1/Setup/Watchlists/AutoLearn or in Station Settings:

Property	Default	Description
Enabled	false	Run autolearn at ExecutionStartTime.
ExecutionStartTime	null	Time of day (UTC), hh:mm:ss, for example 23:00:00.
SelectionThreshold	50	Minimum match score for the no-mask cluster.
MaskedSelectionThreshold	70	Minimum match score for the face-mask cluster.
MaxAutoLearnFacesCount	30	Autolearn faces kept per member and cluster; one is added per day.
NoFaceMaskConfidenceThreshold	-3000	A face joins the no-mask cluster when its FaceMaskConfidence is below this.
FaceMaskConfidenceThreshold	3000	A face joins the face-mask cluster when its FaceMaskConfidence is above this.

Autolearn needs stored match results: it does not work when the video storage mode is None, see Data retention. Disable it on Follower sites, because their detections are not synchronized back to the Leader.

Synchronizing watchlists

Watchlists can be replicated to other places in two ways, both driven by the watchlist update-log stream in RabbitMQ:

• To other sites with the Leader and Follower services (gRPC), so that several installations share one centrally managed watchlist: Leader and Follower setup.
• To edge devices with the edge streams state synchronizer (MQTT), so that smart cameras identify people locally: Edge watchlist sync.