Watch lists

List watch lists

To retrieve a list of watch lists, use the following method:

GET /watch-lists/

The REQUEST contains the following QUERY-STRING PARAMETERS:

Name	Type	Description
`limit`	integer	Number of results to return per page.
`ordering`	string	Field for sorting the request results. Available fields: `id`, `created_date`, `modified_date`.

The list of all available parameters can be found at http://<findface-ip:port>/api-docs.

To find a specific watch list ID in the response, specify values for the limit and ordering parameters to narrow and organize the search results.

CURL example

curl -X GET "http://<findface-ip:port>/watch-lists/?limit=2&ordering=id" \
 -H "Authorization: Token <token>"

If the response is successful (OK: 200), it returns a JSON object that contains the following parameters:

Name	Type	Description
`next_page`	string┃null	Next page.
`prev_page`	string┃null	Previous page.
`results`	[{…}]	Array containing the following parameters. Example.

Note

* – means required parameters. 🆁 – read only.

Name	Type	Description
`id*`	integer 🆁	Watch list ID.
`created_date*`	date-time 🆁	Timestamp indicating when the watch list was created.
`modified_date*`	date-time 🆁	Timestamp indicating when the watch list was last updated.
`active`	boolean	`true` if the watch list is active.
`name*`	string	Name of the watch list. Constraints: Min 1┃Max 256 chars.
`comment`	string	Extended description. Constraints: Min 0┃Max 2048 chars.
`color`	string	Color of the watch list label in hex. Constraints: Min 0┃Max 6 chars.
`notify`	boolean	`true` if sound notifications are enabled for the watch list.
`acknowledge`	boolean	`true` if events that match this watch list require manual acknowledgment.
`camera_groups`	array of integers	IDs of camera groups associated with the watch list.
`face_threshold`	number┃null	Confidence threshold for face detection in the watch list. Constraints: Min 0┃Max 1.
`body_threshold`	number┃null	Confidence threshold for body detection in the watch list. Constraints: Min 0┃Max 1.
`car_threshold`	number┃null	Confidence threshold for vehicle detection in the watch list. Constraints: Min 0┃Max 1.
`ignore_events`	boolean	`true` if events are not created when objects from this watch list are detected.
`send_events_to_external_vms`	boolean	`true` if events that match this watch list must be sent to an external VMS.
`origin`	string	Name of the application module in which the watch list was created. Constraints: Min 0┃Max 256 chars.
`collect_location`	boolean	`true` if cards from this watch list are included in the daily search task. Used only in FindFace CIBR when the FindFace CIBR instance is configured as a puppeteer.

Response example

{
 "next_page": null,
 "prev_page": null,
 "results": [
   {
     "id": 3,
     "created_date": "2025-05-13T12:10:28.303303Z",
     "modified_date": "2025-05-13T12:10:28.303325Z",
     "active": true,
     "name": "Parking watch list",
     "comment": "",
     "color": "cccccc",
     "notify": false,
     "acknowledge": false,
     "camera_groups": [],
     "face_threshold": null,
     "body_threshold": null,
     "car_threshold": null,
     "ignore_events": false,
     "send_events_to_external_vms": false,
     "origin": "ffsecurity",
     "collect_location": false
   },
   {
     "id": 2,
     "created_date": "2025-05-13T11:37:43.593898Z",
     "modified_date": "2025-07-01T15:42:33.537511Z",
     "active": true,
     "name": "Shopping mall watch list",
     "comment": "",
     "color": "cccccc",
     "notify": false,
     "acknowledge": true,
     "camera_groups": [
       2,
       3
     ],
     "face_threshold": 0.702,
     "body_threshold": 0.65,
     "car_threshold": 0.65,
     "ignore_events": true,
     "send_events_to_external_vms": false,
     "origin": "ffsecurity",
     "collect_location": false
   }
 ]
}

Create a new watch list

To add a new watch list, use the following method:

POST /watch-lists/

The REQUEST BODY is required and contains an application/json object with the following parameters:

Name	Type	Description
`active`	boolean	If `true`, the watch list will be active.
`name*`	string	Name of the watch list. Constraints: Min 1┃Max 256 chars.
`comment`	string	Extended description. Constraints: Min 0┃Max 2048 chars.
`color`	string	Color of the watch list label in hex. Constraints: Min 0┃Max 6 chars.
`notify`	boolean	If `true`, sound notifications will be enabled for the watch list.
`acknowledge`	boolean	If `true`, events that match this watch list will require manual acknowledgment.
`camera_groups`	array of integers	IDs of camera groups associated with the watch list.
`face_threshold`	number┃null	Confidence threshold for face detection in the watch list. Constraints: Min 0┃Max 1.
`body_threshold`	number┃null	Confidence threshold for body detection in the watch list. Constraints: Min 0┃Max 1.
`car_threshold`	number┃null	Confidence threshold for vehicle detection in the watch list. Constraints: Min 0┃Max 1.
`ignore_events`	boolean	If `true`, events will not be created when objects from this watch list are detected.
`send_events_to_external_vms`	boolean	If `true`, events that match this watch list will be sent to an external VMS.
`origin`	string	Name of the application module in which the watch list will be created. Constraints: Min 0┃Max 256 chars.
`collect_location`	boolean	If `true`, cards from this watch list can be included in the daily search task. Used only in FindFace CIBR when the FindFace CIBR instance is configured as a puppeteer.

Request example

Tip

This example is provided for reference only. Substitute your own values in the corresponding fields. You only need to fill in the required fields; all other fields will use their default values.

{
 "active": false,
 "name": "A",
 "comment": "AAAAAA",
 "color": "A",
 "notify": false,
 "acknowledge": false,
 "camera_groups": [
   0
 ],
 "face_threshold": 0,
 "body_threshold": 0,
 "car_threshold": 0,
 "ignore_events": false,
 "send_events_to_external_vms": false,
 "origin": "A"
}

For example, you can send these parameters:

{
 "active": true,
 "name": "new watch list",
 "comment": "sample",
 "color": "35a2ee"
}

CURL example

curl -X POST "http://<findface-ip:port>/watch-lists/" \
 -H "Authorization: Token <token>" \
 -H "Content-Type: application/json" \
 -d '{"active":true,"name":"new watch list","comment":"sample","color":"35a2ee"}'

If the response is successful (Created: 201), it returns a JSON object that contains parameters. Example.

Response example

{
 "id": 9,
 "created_date": "2025-07-22T09:36:00.253232Z",
 "modified_date": "2025-07-22T09:36:00.253273Z",
 "active": true,
 "name": "new watch list",
 "comment": "sample",
 "color": "35a2ee",
 "notify": false,
 "acknowledge": false,
 "camera_groups": [],
 "face_threshold": null,
 "body_threshold": null,
 "car_threshold": null,
 "ignore_events": false,
 "send_events_to_external_vms": false,
 "origin": "ffsecurity",
 "collect_location": false
}

Use the watch list ID in the POST request to create a new record.

Useful requests

GET /watch-lists/
POST /watch-lists/
GET /watch-lists/{id}/
DELETE /watch-lists/{id}/
PATCH /watch-lists/{id}/
POST /watch-lists/{id}/purge/
GET /watch-lists/count/
POST /watch-lists/purge_all/