JSON Web API Search

Performs a one-to-many comparison of the uploaded face images with stored biometric templates in order to find matching persons in the database.

This method creates biometric feature vectors for all of the provided face images. To perform the comparisons, all biometric templates to compare are then fetched from the database (their digital signature is verified and they may get decrypted) according to the specified list of tags.

As the process of fetching (verification and decryption) of the biometric face templates from the database is more time-consuming than the actual comparison with the calculated feature vectors, we support bulk processing of multiple input images here. This speeds up the average comparison time a lot.

Anyway, the method has a timeout (a backend response read timeout), that may abort the call after 10 minutes.

Request

POST /api/face/v1/search

Request Body

The HTTP request body contains the array of images to enroll.

Content type: application/json

{
  "images": [
    {
      "image": "string"
    }
  ],
  "tags": [
    "string"
  ],
  "topMatches": true
}

The Search request object has a the fields as follows:

images

An array of one or more base64 encoded facial images of the persons to search for. Each image has to contain exactly a single face, otherwise the call is aborted immediately to avoid unnecessary template fetches.

tags

List of tags that need to be assigned to the biometric templates to search. Only templates that have all of these tags applied are considered in the search. If no tag is specified, all available templates are searched.

top_matches

By default only a list of identified classes is returned. Optionally, a list of the top 10 best matches can be delivered, if this property is set to true.

The maximum API request size is 50 MB. This is the only limitation for the number of input images.

Request Headers

This API requires a valid JWT in the Authorization request header and accepts an optional reference number.

Authorization	Required Bearer authentication. Please refer to BWS API Authentication for a description of how to provide a valid JWT here.
Reference-Number	Optional, client specific reference number, which will be added to the BWS bookkeeping as well as to the response header. You typically use this reference to link the resulting BWS bookkeeping entries with your logs.

Response

Response Body

Content type: application/json

{
  "status": "SUCCEEDED",
  "errors": [
    {
      "errorCode": "string",
      "message": "string"
    }
  ],
  "imageProperties": [
    {
      "rotated": 0,
      "faces": [
        {
          "leftEye": {
            "x": 0,
            "y": 0
          },
          "rightEye": {
            "x": 0,
            "y": 0
          },
          "textureLivenessScore": 0,
          "motionLivenessScore": 0,
          "movementDirection": 0
        }
      ],
      "qualityScore": 0,
      "qualityAssessments": [
        {
          "check": "string",
          "score": 0,
          "message": "string"
        }
      ],
      "frameNumber": 0
    }
  ],
  "result": [
    {
      "matches": [
        {
          "classId": 0,
          "score": 0
        }
      ]
    }
  ]
}

On success the API returns an Enrollment response object with the fields as follows:

status

The status of the BWS job that processed the request. The following fields are typically only set, when the job has succeeded.

errors

A list of errors that might have occurred while the request has been processed.

imageProperties

The calculated image properties for each of the provided images in the given order.

result

For each input image a SearchResult is created and returned in the order of the provided input images. A SearchResult again is a sorted list (by score) of TemplateMatchResult messages containing the identified classes or the best matches, depending on the topMatches flag in the request.

classId

Class ID of the person the matched template belongs to.

score

The calculated similarity score for this class in the range between 0.0 and 1.0. The higher the score, the more likely the template matches the calculated feature vector.

Remarks

Please note, that this method might be a long running task, as all biometric templates need to be fetched from the database, its digital signature need to be verified and the template may need to be decrypted before it can be compared with the calculated face feature vectors. Therefore using bulk processing (sending more than one image simultaneously) and restriction to user-groups (by using tags) can speed up this method immense.

BWS Errors

Possibly some errors might have been reported:

FaceNotFound

No suitable face was found in at least one of the provided images.

MultipleFacesFound

More than one face has been found in at least one of the provided images.

HTTP Status Codes

The call returns one of the standard HTTP status codes, e.g.:

200 (OK)

The response body contains the Enrollment response object as described above.

400 (Bad Request)

The call failed, typically due to an invalid argument. The response body contains a JSON object with the reported gRPC error code and message.

401 (Unauthorized)

The request does not have valid authentication credentials for the operation.

408 (Request Timeout)

Client application cancelled the request.

500 (Internal Server Error)

Server experienced some unexpected behaviour.

503 (Service Unavailable)

The service is currently unavailable. This is a most likely a transient condition and may be corrected by retrying with a backoff.

Response Headers

All successful BWS calls return a response header containing additional information about the request:

jobid	The Job-ID (a GUID) that has been assigned to this BWS call.
bws-version	The version of the BWS gRPC service.
reference-number	An optional reference number as provided in the request header.
date	The timestamp when the request has been received at the server.
...	Other headers that might have been added by the server (NGINX, Kestrel, ...) that was handling the request.