REST API

The SmartFace REST API (Representational State Transfer Application Programming Interface) enables interaction between the SmartFace and your system by allowing requests for data and the manipulation of resources on a server, using standard HTTP methods like GET, POST, PUT, DELETE, etc. Exchanging of the data is done in the JSON format and it can be easily consumed by various clients, including web browsers and mobile applications.

Sets of REST API Endpoints

We provide two sets of REST API endpoints:

the SmartFace Platform REST API - a full set of available features (API documentation here)
the Lightweight Facial Identification Service REST API - a subset of features matching the the Lightweight Facial Identification Service - LFIS functionality (API documentation here)

The SmartFace Platform REST API supports all of the REST API features available. This covers endpoints related to using and configuring cameras, whether RTSP or Edge stream, accessing faces, frames, images, individuals, pedestrians, watchlists, watchlistmembers, tracklets, record groupings and video records. On top of that you have access to setup and configuration of data storage, database cleanup, previews, allowed features, search session cleanup and the endpoint to get the current version.

The REST API for the Lightweight Facial Identification Service is a subset of SmartFace Platform REST API endpoints. The list of endpoints in the full set is substantial however the most used endpoints are related to creating watchlists, registering their members, searching incoming images to existing watchlists, checking two faces against each other, and/or doing a liveness check to avoid spoof attacks. The Lightweight Facial Identification Service covers all of these most used endpoints.

How to use the SmartFace REST API

The REST API for the SmartFace allows you to control many of its aspects and use its features directly, whether using the swagger or programmatically with your favorite programming language.

Use REST API programmatically

You can connect the SmartFace with the world using the REST API. This API is accessible by default via port 8098 on the server of installation. It does have a web interface using Swagger. Swagger documents all available endpoints and services.

You can connect and make calls to the Lightweight Facial Identification Service via any programming language supporting REST API calls. Understanding schemas and request parameters is possible by using the Swagger web interface portal.

Use REST API via Web Interface

By accessing your server installation on port 8098 (such as http://localhost:8098) you will see a list of endpoints available in several groups. If you click on a group of endpoints you can collapse or expand it. Once you click on a group you have a set of endpoints visible. You can click on an endpoint to see the parameters and the responses available.

Watchlists endpoint

When you click Try it out button you can make a call directly from the web interface. Once you have prepared the request you can click Execute to execute the request.

Once the request is executed you will receive a response. The responses differ per endpoint.

SmartFace Platform REST API

The SmartFace Platform REST API covers a vast amount of functionalities, allowing you to view, manage, and update data, camera and platform configuration and initiate several advanced functions. This represents all of the REST API features available and is split into a list of endpoints.

List of available endpoints:

Camera
Detection
EdgeStream
Face
Frame
Image
Individual
LiveGrouping
Pedestrian
RecordGrouping
SetupDataStorage
SetupDbCleanup
SetupFeatures
SetupPreview
SetupSearchSessionsCleanup
SetupWatchlistAutoLearn
Tracklet
Version
VideoRecord
Watchlists
WatchlistMembers

Camera

The Camera endpoint serves to manage cameras ( to view, register, update and delete them) and to retrieve their Tracklets and Frames. The endpoint supports GET , DELETE , PUT , and POST methods.

Detection

The Detection endpoint serves to send an image to detect a pedestrian or an object. It also retrieves information about the bounding box coordinates, order of the object/pedestrian and object type. The endpoint supports POST method.

EdgeStream

The EdgeStream endpoint serves to manage Edge cameras ( to view, register, update and delete them) and also to view and setup Watchlist Synchronization with the EdgeStream Cameras. The endpoint supports GET , DELETE , PUT , and POST methods.

Face

The Face endpoint serves to retrieve and manage faces (images and associated templates for Face Recognition) and also provides additional search functionalities: search for a similar face, do a spoof/liveness check and verify whether two images belong to one person. The endpoint supports GET , DELETE , and POST methods.

Frame

The Frame endpoint serves to retrieve and delete Frames - full images gathered from the Cameras and Edge Cameras. These are used for face/pedestrian/object detection. The endpoint supports GET and DELETE methods.

Image

The Image endpoint serves to get you a stored image. Each image is stored using a unique string GUID value. Using the unique GUID string, you can show and download an image - whether a face, a frame, a pedestrian or an object. The image can be resized during the retrieving process. The endpoint supports GET method.

Individual

The Individual endpoint serves to retrieve Individuals, retrieve their Tracklets, delete Individuals, split them and merge them and then provide search functionality within individuals - search for individuals by providing an image. Individuals are created by the grouping functionality. The endpoint supports GET , DELETE , and POST methods.

LiveGrouping

The LiveGrouping endpoint serves to enable, delete and manage the grouping functionality using the live video streams and edge streams. From here you can also link and unlink cameras to/from a grouping and retrieve grouping data - cameras, individuals and frames. The endpoint supports GET , DELETE , PUT , and POST methods.

Pedestrian

The Pedestrian endpoint serves to retrieve pedestrian information and metadata, whether by its IDs, or all pedestrians; and to delete them. The endpoint supports GET , and DELETE methods.

RecordGrouping

The RecordGrouping endpoint serves to create, delete, retrieve information and manage the grouping functionality using the video records - investigation videos. From here you can also link and unlink specified vides to/from a grouping and retrieve grouping data - videos, individuals and frames. The endpoint supports GET , DELETE , PUT , and POST methods.

SetupDataStorage

The SetupDataStorage endpoint serves to retrieve and update the configuration of the SmartFace Platform data storage. More information is available in the guides section. The endpoint supports GET , and PUT methods.

SetupDbCleanup

The SetupDbCleanup endpoint serves to retrieve and update the configuration of the SmartFace Platform Automatized Clean Up. More information is available in the guides section. The endpoint supports GET , and PUT methods.

SetupFeatures

The SetupFeatures endpoint serves to retrieve and update the configuration of the SmartFace Platform and SmartFace Station features. The endpoint supports GET , and PUT methods.

SetupPreview

The SetupPreview endpoint serves to retrieve and update the configuration of the Preview Setup for the SmartFace Platform and the SmartFace Station. This includes used colours in the SmartFace Preview. The endpoint supports GET , and PUT methods.

SetupSearchSessionsCleanup

The SetupSearchSessionsCleanup endpoint serves to retrieve and update the configuration of the Search Session Cleanup of the SmartFace Platform, thus allowing you to set up automatized cleanup. The endpoint supports GET , and PUT methods.

SetupWatchlistAutoLearn

The SetupWatchlistAutoLearn endpoint serves to retrieve and update the configuration of the SmartFace Platform’s Autolearn feature. More information is available in the SmartFace Platform’s manual. The endpoint supports GET , and PUT methods.

Tracklet

The Tracklet endpoint serves to retrieve and delete tracklets and it’s information, whether by its IDs, or as paged collections. The endpoint supports GET , DELETE methods.

Version

The Version endpoint serves to retrieve version information about the SmartFace Platform and the used database. The endpoint supports GET method.

VideoRecord

The VideoRecord endpoint serves to create, retrieve, update and delete video records - stored videos and information. It also allows to retrieve tracklet and frame information, reset the video including the stored metadata and also retrieve and update tag information. The endpoint supports GET , DELETE , PUT , and POST methods.

Watchlists

The Watchlists endpoint serves to create, retrieve, update and delete Watchlists. It also allows searching for matches within the specified watchlist(s) using either an image or the biometric template . The endpoint supports GET , DELETE , PUT , and POST methods.

WatchlistMembers

The WatchlistMembers endpoint servers to create, retrieve, update and delete Watchlist Members. It also allows to retrieve, add and update Watchlist Member’s faces, link and unlink a Watchlist Member and register a Watchlist Member. The endpoint supports GET , DELETE , PUT , and POST methods.

Lightweight Facial Identification Service REST API

The Lightweight Facial Identification Service REST API provides the most used REST API endpoints of the SmartFace Platform. These are organized into 5 categories:

Watchlist management
Watchlist members management
Identification
Verification
Liveness

It also provides the Object/Pedestrian Detection funcionality.

Watchlist management

Retrieve information about existing watchlists

You can easily retrieve information about existing watchlist(s) by using these 2 methods:

Retrieve information about ALL Watchlists

GET /api/v1/Watchlists

This endpoint allows you to list all existing watchlists and provide information about them. The output is paginated, eg. the list of Watchlists is split into pages where each page has a set amount of Watchlists. Page number, page size and sorting order can be specified. You can also show the total items count.

The optional parameters can be used by adding them after the endpoint URL such as when you want to have a paginated list of Watchlists in ascending order where there are 10 Watchlists on each page, plus you want to know the total count of Watchlists, please use this call: http://localhost:8098/api/v1/Watchlists?Ascending=true&PageSize=10&ShowTotalCount=true

Successful response contains a set of values for each found watchlist, including:
threshold - shows the the default threshold to be used against the matching score when doing a face matching
palmThreshold - shows the default threshold to be used against the matching score when doing a palm matching
previewColor - shows the color of the watchlist name when mentioned in the SmartFace station (currently not used in the Lightweight Facial Identification Service). The color is in a hexadecimal format, such as #012abc or #01a
id - shows the unique identifier used by Lightweight Facial Identification Service internally for referencing a watchlist. When referring to a watchlist in your requests, this is the value to be used.

Retrieve information about ONE Watchlist

GET /api/v1/Watchlists/{id}

This endpoint allows you to retrieve information about a specific endpoint if you know its unique identifier (id). You will get information about one watchlist at a time.

For a sample watchlist with an id equal to 8f02f8b6-dd02-4dd1-bc24-bc559ce16705 you would have a request URL looking like this: http://localhost:8098/api/v1/Watchlists/8f02f8b6-dd02-4dd1-bc24-bc559ce16705

Create a new watchlist

POST /api/v1/Watchlists

You can create a new watchlist using this endpoint. Before you can proceed you need to decide several parameters: displayName, fullName, threshold, palmThreshold, and preview color.

The recommended default threshold is 40 for face mathing. The recommended default palm threshold is 75. These values can be adjusted to match your specific needs.

Change a watchlist’s attributes

PUT /api/v1/Watchlists

You can change a watchlist with the endpoint. If a watchlist with such a unique identifier (id) does not exist, it will create a new watchlist with desired parameters. The input parameters are matching the request parameters of creating a watchlist.

Delete a watchlist

DELETE /api/v1/Watchlists/{id}

Deletes a watchlist by its id. The deleted watchlist does not delete associated watchlist members. To remove watchlist members you need to delete them directly.

Watchlist members management

You can manage watchlist members for each Watchlist. One Watchlist member can be linked to more than one Watchlist.

Get information about existing watchlist members

There are a few ways how to get information about Watchlist Members.

All

GET /api/v1/WatchlistMembers

Using this endpoint you can get a paged list of all Watchlist Members. You can order the list and watch the list split into pages that are sized to your liking.

# Sample output:
{
  "totalItemsCount": null,
  "items": [
    {
      "displayName": "John Wick",
      "fullName": "John Wick",
      "note": null,
      "labels": [],
      "id": "45d9843b-6776-4f9c-a000-90da442420f0",
      "createdAt": "2022-10-05T12:53:47.726661Z",
      "updatedAt": "2022-10-05T12:53:56.620247Z"
    },
    {
      "displayName": "James Bond",
      "fullName": "James Bond",
      "note": "",
      "labels": [],
      "id": "03e4a2d6-98f6-4565-8081-e75bbb9efb34",
      "createdAt": "2022-10-26T11:44:37.456912Z",
      "updatedAt": null
    },
    {
      "displayName": "Lara Croft",
      "fullName": "Lara Croft",
      "note": "",
      "labels": [],
      "id": "0ebfeebc-3859-49d8-a798-acd273b4a017",
      "createdAt": "2022-11-21T11:51:30.675498Z",
      "updatedAt": null
    }
  ],
  "pageSize": 3,
  "pageNumber": 1,
  "previousPage": null,
  "nextPage": null
}

By ID

GET /api/v1/WatchlistMembers/{id}

You can get information about only 1 Watchlist Member as long as you know the member’s id. You can easily get the id of a member in the GET /api/v1/WatchlistMembers.

Linked to watchlist

GET /api/v1/Watchlists/{id}/WatchlistMembers

You can also get a list of Watchlist Members linked to any Watchlist using this endpoint. You need to know the Watchlist id value. The id value can be retrieved from GET /api/v1/Watchlists.

Register new watchlist member

POST /api/v1/WatchlistMembers/Register

You can register a watchlist member using this endpoint. It allows a complex enrollment as you can enroll using a face image, palm image or without an image, set custom a id, choose watchlists to enroll into, and also set registering conditions that need to be fulfilled to enroll a member.

If you preset an id you would like to use it will be set for the member you are enrolling. If you omit this information it will be set automatically.

"id": "juraj-custom-id",

To register a new watchlist member you canprovide an image that contains the member’s modality, such as a face or palm. The image needs to be provided in the base64 coding and is part of the images.data REST API call.

"images": [
{
  "modality": "Face",
  "faceId": null,
  "palmId": null,
  "data": ""
}
],

ℹ️ Base64 is a common encoding used to represent data as text. This allows you to send an image via REST API to the Lightweight Facial Identification Service to be processed.

You need to select at least one Watchlist to enroll in using this endpoint. You can however set several Watchlists at once if needed.

# Choosing Watchlists to enroll into
"watchlistIds": [
    "Watchlist-id-one", "Watchlist-id-two", "Watchlist-id-three"
  ],

Detectors

Setting up detector configuration is meant to ensure the quality of the enrollment pictures so you will not register a member with an image with too low resolution or an image with otherwise low quality. There are currently configurations for face and palm detectors. Both are using the same attributes.

The minFaceSize and maxFaceSize allow you to set the minimum and maximum face size of the image, similarly minPalmSize and maxPalmSize allow you to set the minimum and maximum palm size of the image. Other sizes will be ignored by the detector. The values of maxFaces and maxPalms set the maximum amount of faces and palms to be processed on 1 image. This is related to the possibility to register more people from one image. confidenceThreshold is applicable for both modalities and sets the minimum detection quality to pass the threshold to be considered a successful detection.

Face detector

# Setting up the detector for enrollment
"faceDetectorConfig": {
    "minFaceSize": 30,
    "maxFaceSize": 600,
    "maxFaces": 20,
    "confidenceThreshold": 1450
  },

Palm detector

"palmDetectorConfig": {
    "minPalmSize": 200,
    "maxPalmSize": 1200,
    "maxPalms": 20,
    "confidenceThreshold": 5000
  }

Additional customer information called labels can be added. These labels need to be defined once Lightweight Facial Identification Service wise but once you set the information it can be passed onto the Lightweight Facial Identification Service for each member during enrollment. For more information about labels please read here.

Link Watchlist Member to different watchlist

A Watchlist Member can be enrolled into several Watchlists. However during the registration phase possibly not all Watchlists needed are known. You can adjust this by freely linking and unlinking Members to and from Watchlists.

Link

POST /api/v1/WatchlistMembers/LinkToWatchlist

This endpoint allows you to set a list of Members(N) to be linked into a Watchlist(1).

Unlink

POST /api/v1/WatchlistMembers/UnlinkFromWatchlist

This endpoint allows you to set a list of Members(N) to be unlinked from a Watchlist(1).

Delete watchlist member (from all watchlists)

DELETE /api/v1/WatchlistMembers/{id}

This endpoint allows you to completely remove a member from the system including its membership in all Watchlists the member was enrolled into.

Identification

When you provide an image you can identify a person(s) on the image by finding a match with Watchlist Members in the Lightweight Facial Identification Service. The identification process goes through few steps: detection, extraction and matching. These steps are seamless and are all done in the background when an identification is requested.

When SmartFace detects a face, the system creates a cropped image of the found face. The crop is used for the identification process. Successful face matching is when the matching score is higher than the matching threshold.

Face identification can provide additional information. You can show/hide this information as required.

"faceFeaturesConfig": {
    "age": true,
    "gender": true,
    "faceMask": true,
    "noseTip": true,
    "yawAngle": true,
    "pitchAngle": true,
    "rollAngle": true
  }

The Lightweight Facial Identification Service can provide information on whether the detected person(s) wears a mask. The confidence threshold can be adjusted.

"faceMaskConfidenceRequest": {
    "faceMaskThreshold": 3000
  },

When you are identifying person(s) on an image you might be interested in liveness of the detected person(s). The liveness/spoof check can be done as a part of the identification process without the need to run a separate liveness check. For a better understanding of how to evaluate liveness using the Lightweight Facial Identification Service REST API please see the liveness subsection.

See below the full sample request for POST /api/v1/Watchlists/Search

{
  "image": {
    "data": ""
  },
  "watchlistIds": [
    "sample_watchlist_id"
  ],
  "threshold": 40,
  "maxResultCount": 1,
  "faceDetectorConfig": {
    "minFaceSize": 35,
    "maxFaceSize": 600,
    "maxFaces": 20,
    "confidenceThreshold": 450
  },
  "faceDetectorResourceId": "cpu",
  "templateGeneratorResourceId": "cpu",
  "faceMaskConfidenceRequest": {
    "faceMaskThreshold": 3000
  },
  "faceFeaturesConfig": {
    "age": true,
    "gender": true,
    "faceMask": true,
    "noseTip": true,
    "yawAngle": true,
    "pitchAngle": true,
    "rollAngle": true,
    "sharpness": true,
    "brightness": true,
    "tintedGlasses": true,
    "heavyFrame": true,
    "glassStatus": true
  },
  "spoofDetectorResourceIds": [
    "none"
  ],
  "spoofCheckConfig": {
    "distantLivenessScoreThreshold": 90,
    "nearbyLivenessScoreThreshold": 90,
    "distantLivenessConditions": "default",
    "nearbyLivenessConditions": "default",
    "keepEvaluatingConditionsAfterFirstFail": false
  }
}

Identification in all watchlists

If you would like to search all watchlists using an image of a person(s) you can use the endpoint POST /api/v1/Watchlists/Search. As you do not have a specific Watchlist in mind you can omit the list of Watchlists by keeping the watchlistIds array empty.

"watchlistIds": [
    
],

Identification in chosen watchlist(s)

If you would like to search only in set watchlists using an image of a person(s) you can use the same endpoint POST /api/v1/Watchlists/Search but you need to specify the watchlists to be searched within by listing their Watchlist Ids ( watchlistIds) in the array.

"watchlistIds": [
    "watchlist-id-first",
    "watchlist-id-second",
    "watchlist-id-third"
],

ℹ️ You can get the Watchlist Ids from the endpoint GET /api/v1/Watchlists.

Get the top 10 candidates

By default when you request results of the search (identification) endpoint the maxResultCount parameter is set to 1. This means that you will get only the most matching person - ie. the face with the highest score that is over the threshold. Depending on your threshold levels and the similarity of the Watchlist Members you can request more candidates as a result of the search endpoint.

This might be useful to receive a list of similar candidates. It is recommended to set the threshold lower than the standard score so more faces would pass this threshold. So for an example instead of threshold equal to 40, you can lower it to the value of 20 and set the maxResultCount to the value of 10. In this case, you can receive up to 10 Watchlist Members that would likely be similar to each other.

Verification

The Lightweight Facial Identification Service does provide information about Watchlist Members or whether they are part of said Watchlist(s). On top of this Lightweight Facial Identification Service can be used to provide additional information about individual photos/images even if the detected persons are not, or are not meant to be registered in any Watchlists.

Verification of the one-to-one comparison

Sometimes it is useful to find out whether 2 images depict the same person. To retrieve the confidence that two faces belong to the same person can be done using POST /api/v1/Faces/Verify endpoint. To verify two images against each other you need to provide probeImage and referenceImage in the form of base64 encoded string. To ensure the quality of the image used for verification please set configuration for the face detector.

Liveness

Passive liveness detection is a process of determining whether the presented face is a real person, without requiring the user to perform any additional action.

The Liveness is fully described in the SmartFace Platform so to avoid duplicity, please for more information about the Liveness read here.

Object/Pedestrian Detection

The Detection functionality allows you to detect Pedestrians and Objects on images using the LFIS via the REST API. The POST /api/v1/Detect endpoint uses an image encoded as the base64 delivered in the data field. Depending on the resources used, you can retrieve lists of objects and pedestrians detected on the image. Detector can be configured, including the minimum and maximum sizes, the amount of objects/pedestrians detected or the confidence thresholds.

You can also choose what categories of objects to detect.

Other functionalities

The REST API provides additional endpoints for various uses and this article gives only an oversight of the most common functionality. For full description please read the API documentation.

REST API

Sets of REST API Endpoints#

How to use the SmartFace REST API#

Use REST API programmatically#

Use REST API via Web Interface#

SmartFace Platform REST API#

Camera#

Detection#

EdgeStream#

Face#

Frame#

Image#

Individual#

LiveGrouping#

Pedestrian#

RecordGrouping#

SetupDataStorage#

SetupDbCleanup#

SetupFeatures#

SetupPreview#

SetupSearchSessionsCleanup#

SetupWatchlistAutoLearn#

Tracklet#

Version#

VideoRecord#

Watchlists#

WatchlistMembers#

Lightweight Facial Identification Service REST API#

Watchlist management#

Retrieve information about existing watchlists#

Retrieve information about ALL Watchlists#

Retrieve information about ONE Watchlist#

Create a new watchlist#

Change a watchlist’s attributes#

Delete a watchlist#

Watchlist members management#

Get information about existing watchlist members#

All#

By ID#

Linked to watchlist#

Register new watchlist member#

Link Watchlist Member to different watchlist#

Link#

Unlink#

Delete watchlist member (from all watchlists)#

Identification#

Identification in all watchlists#

Identification in chosen watchlist(s)#

Get the top 10 candidates#

Verification#

Verification of the one-to-one comparison#

Liveness#

Object/Pedestrian Detection#

Other functionalities#