Skip to main content

Biometric Identification Service REST API

The Biometric Identification Service exposes its functionality over a REST API: requests and responses are exchanged as JSON over standard HTTP methods (GET, POST, PUT, DELETE), so it can be consumed from any language or client that speaks HTTP.

This page documents the most-used endpoints, organized into five categories:

It also provides object / pedestrian detection functionality.

For the complete endpoint and schema reference – every operation, parameter, and response model – see the generated REST API reference.

How to call the API​

The API is served over HTTP (by default on port 8098 of the deployment). Every deployment ships a Swagger web interface that documents all available endpoints and lets you inspect request/response schemas and call endpoints interactively:

  • Open the server on its API port (for example http://localhost:8098) to browse the endpoint groups. Expand a group, pick an endpoint, and review its parameters and responses.
  • Use Try it out → Execute to issue a call directly from the browser and see the response.

You can also call the API programmatically from any language with an HTTP client.

Watchlist management​

A watchlist is the server-side gallery a probe is matched against.

Retrieve all watchlists​

GET /api/v1/Watchlists

Lists all existing watchlists. The output is paginated – page number, page size, and sort order can be specified, and you can request the total item count. For example, an ascending page of 10 with the total count:

http://localhost:8098/api/v1/Watchlists?Ascending=true&PageSize=10&ShowTotalCount=true

Each returned watchlist includes:

  • threshold – default threshold applied to the matching score for face matching.
  • palmThreshold – default threshold applied to the matching score for palm matching.
  • previewColor – display color of the watchlist name (hexadecimal, e.g. #012abc); not used by the service itself.
  • id – the unique identifier used internally to reference a watchlist; use this value when referring to a watchlist in your requests.

Retrieve one watchlist​

GET /api/v1/Watchlists/{id}

Retrieves a single watchlist by its unique identifier (id):

http://localhost:8098/api/v1/Watchlists/8f02f8b6-dd02-4dd1-bc24-bc559ce16705

Create a watchlist​

POST /api/v1/Watchlists

Creates a new watchlist. Set displayName, fullName, threshold, palmThreshold, and previewColor. The recommended default is 40 for the face threshold and 75 for the palm threshold; adjust to your needs.

Change a watchlist's attributes​

PUT /api/v1/Watchlists

Updates a watchlist. If no watchlist with the given id exists, one is created with the supplied parameters. Input parameters match those of watchlist creation.

Delete a watchlist​

DELETE /api/v1/Watchlists/{id}

Deletes a watchlist by its id. Deleting a watchlist does not delete its members – remove members directly if needed.

Watchlist members management​

A watchlist member is one enrolled identity. A member can be linked to more than one watchlist.

Get watchlist members​

There are a few ways 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 split it into pages sized to your liking.

{
  "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 one watchlist member as long as you know the member's id. You can easily get the id of a member from 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, which can be retrieved from GET /api/v1/Watchlists.

Register a member​

POST /api/v1/WatchlistMembers/Register

Registers a watchlist member. Supports complex enrollment: from a face image, a palm image, or without an image; with a custom id; into one or more watchlists; and with registering conditions that must be met to enroll.

If you preset an id, it is used for the member; otherwise one is assigned automatically:

"id": "custom-id",

Provide the member's biometric as a base64-encoded image in images.data:

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

Select at least one watchlist to enroll into (several are allowed):

"watchlistIds": [
  "watchlist-id-one", "watchlist-id-two"
],

Detectors. Detector configuration guards enrollment quality so low-resolution or otherwise poor images are rejected. Face and palm detectors share the same attributes: minFaceSize / maxFaceSize (and minPalmSize / maxPalmSize) bound the accepted size range, maxFaces / maxPalms cap how many are processed per image (enabling multi-person enrollment from one image), and confidenceThreshold sets the minimum detection quality.

"faceDetectorConfig": {
  "minFaceSize": 30,
  "maxFaceSize": 600,
  "maxFaces": 20,
  "confidenceThreshold": 1450
},
"palmDetectorConfig": {
  "minPalmSize": 200,
  "maxPalmSize": 1200,
  "maxPalms": 20,
  "confidenceThreshold": 5000
}

Custom labels can also be attached to a member during enrollment (labels must be defined once before use).

A member can belong to several watchlists, and membership can be adjusted after registration.

POST /api/v1/WatchlistMembers/LinkToWatchlist – link a list of members to a watchlist.

POST /api/v1/WatchlistMembers/UnlinkFromWatchlist – unlink a list of members from a watchlist.

Delete a member​

DELETE /api/v1/WatchlistMembers/{id}

Completely removes a member from the system, including membership in every watchlist it was enrolled into.

Identification​

Identification answers "who is this?" by searching a probe against one or more watchlists. It is available for two modalities:

Identification runs detection, template extraction, and matching seamlessly in the background. A match is successful when its score exceeds the matching threshold.

Facial identification​

Provide an image to identify the person(s) on it against watchlist members' faces. A cropped image of each detected face is used for matching.

Face identification can optionally return additional attributes:

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

A face-mask confidence threshold can be adjusted:

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

A liveness / spoof check can be performed as part of identification, without a separate call.

Full sample request for POST /api/v1/Watchlists/Search (image.data is the base64-encoded image):

{
  "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​

To search all watchlists with an image, use POST /api/v1/Watchlists/Search. As you have no specific watchlist in mind, omit the list of watchlists by keeping the watchlistIds array empty:

"watchlistIds": [

],

Identification in chosen watchlist(s)​

To search only specific watchlists, use the same POST /api/v1/Watchlists/Search endpoint but specify the watchlists to search within by listing their watchlist ids in the watchlistIds array:

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

Get the top 10 candidates​

By default, the maxResultCount parameter is set to 1. This means you get only the most matching person – 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.

Define identification properties​

This is useful to receive a list of similar candidates. It is recommended to set the threshold lower than the standard score so more faces pass it. For example, instead of a threshold of 40, lower it to 20 and set maxResultCount to 10. In this case you can receive up to 10 watchlist members that are likely similar to each other.

The minFaceSize and maxFaceSize values set the range of face sizes considered for identification. Smaller or larger detections are ignored.

Palm identification​

Provide a palm image to identify a person against watchlist members' palms. As with faces, detection, extraction, and matching run in the background, and a cropped palm is used for matching.

Full sample request for POST /api/v1/Watchlists/SearchByPalm (image.data is the base64-encoded image):

{
  "image": {
    "data": ""
  },
  "watchlistIds": [
    "sample_watchlist_id"
  ],
  "threshold": 40,
  "maxResultCount": 1,
  "palmDetectorConfig": {
    "minPalmSize": 200,
    "maxPalmSize": 1200,
    "maxPalms": 1,
    "confidenceThreshold": 5000
  },
  "palmDetectorResourceId": "cpu",
  "spoofDetectorResourceIds": [
    "none"
  ],
  "spoofCheckConfig": {
    "livenessScoreThreshold": 85
  }
}

A liveness / spoof check can be performed as part of palm identification, without a separate call.

Identification in all watchlists​

To search all watchlists with a palm image, use POST /api/v1/Watchlists/SearchByPalm and keep the watchlistIds array empty:

"watchlistIds": [

],

Identification in chosen watchlist(s)​

To search only specific watchlists, use the same POST /api/v1/Watchlists/SearchByPalm endpoint but list the target watchlist ids in the watchlistIds array:

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

Get the top 10 candidates​

By default, the maxResultCount parameter is set to 1, so you get only the most matching person – the palm with the highest score over the threshold. Depending on your threshold levels and the similarity of the watchlist members, you can request more candidates.

Define identification properties​

This is useful to receive a list of similar candidates. It is recommended to set the threshold lower than the standard score. For example, instead of a threshold of 40, lower it to 20 and set maxResultCount to 10 to receive up to 10 likely-similar members.

The minPalmSize and maxPalmSize values set the range of palm sizes considered for identification. Smaller or larger detections are ignored.

Verification​

Verification answers "is this the claimed person?" – a one-to-one comparison. Face only.

POST /api/v1/Faces/Verify

Returns the confidence that two faces belong to the same person. Provide probeImage and referenceImage as base64-encoded strings. Set the face detector configuration to guard the quality of the images used for verification.

Liveness​

Passive liveness determines whether the presented biometric is a real person, without requiring any user action. The service supports liveness for both face and palm modalities, and it can run inline within an identification call (via spoofDetectorResourceIds / spoofCheckConfig) or as a dedicated spoof check.

See the Liveness feature page for how liveness fits the overall flow.

Object / pedestrian detection​

The service can also detect pedestrians and objects on images via the REST API. The POST /api/v1/Detect endpoint takes an image encoded as base64 in the data field and, depending on the resources used, returns lists of objects and pedestrians detected on the image. The detector is configurable, including the minimum and maximum sizes, the number of objects / pedestrians detected, and the confidence thresholds. You can also choose which categories of objects to detect.

Full reference​

For the complete, generated endpoint and schema reference, see the Biometric Identification Service REST API reference. The same endpoints are browsable via the Swagger UI on any deployed instance.