JSON Web API Enroll

Performs a biometric enrollment (or training) of a single class with one or more images containing the face of the person to enroll. With this method a new biometric face template is created and stored. It can be used to create a completely new biometric template, to update an existing template or even to upgrade an existing template to a newer encoder version.

The created template is persisted to a storage, addressed by its Biometric Class ID (BCID). Beside of a compact version of the biometric template (used for face matching purposes), an enhanced version of the template is stored. The enhanced version contains at least all calculated face features (standard template) and optionally also the thumbnails of the enrolled faces (full version), which are needed for upgrades to newer encoder versions. The enhanced template versions are always encrypted, the compact version is encrypted if required by the configuration of the client (slows down search requests).

Request

POST /api/face/v1/enroll/{classId}

Path Parameter

classId

The unique class ID of the enrolled person. The class ID is a 64-bit positive number, managed by the client.

This ID, together with a storage name and a partition ID will make up the Biometric Class ID (BCID), which is used to address the created biometric template.

Request Body

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

Content type: application/json

[
  {
    "image": "string"
  }
]

An array of one or more base64 encoded images with the faces to enroll. Each image should contain a single face and all faces, of course, should belong to the same person. Images with no face or multiple faces on it will be ignored.

An empty array is allowed. In this case this method simply returns the status of an existing template and, if possible, upgrades an existing template to a newer encoder version.

The maximum API request size is 50 MB.

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
    }
  ],
  "performedAction": "NONE",
  "enrolledImages": 0,
  "templateStatus": {
    "classId": 0,
    "available": true,
    "enrolled": "string",
    "tags": [
      "string"
    ],
    "encoderVersion": 0,
    "featureVectors": 0,
    "thumbnailsStored": 0,
    "thumbnails": [
      {
        "enrolled": "string",
        "image": "string"
      }
    ]
  }
}

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.

performedAction

The actual action performed. This is a value out of the EnrollmentAction enumeration:

NONE

No action was performed. This typically happens, if no input images have been provided and there is no existing template that needs to be upgraded.

NEW_TEMPLATE_CREATED

A new template has been created from the provided input images.

TEMPLATE_UPDATED

An existing template has been updated. The features of the provided images have been added to the existing template to create a new template.

TEMPLATE_UPGRADED

A new template has been created from the provided input images and the enrollment images of an existing old version template, i.e. an existing template has been upgraded to the current encoder version.

ENROLLMENT_FAILED

The enrollment process generated some errors (see the errors field) and no action was performed.

enrolledImages

Number of newly enrolled images. There might be less images enrolled than have been delivered due to problems extracting the needed face features.

templateStatus

The JSON serialized FaceTemplateStatus of the generated (or existing) face template without any face thumbnails.

BWS Errors

In case that the performed_action field is set to ENROLLMENT_FAILED, at least one of the following errors is reported in the errors field:

NoSuitableFaceImage

We could not find a single suitable face in any of the provided images to perform a face enrollment. All images either show no face or multiple faces. Please refer to the quality check results of the images, which should contain failed results for the performed quality checks:

• FaceFound: Check for at least one found face.
• SingleFaceOnImage: Check for exactly one found face.

NoFeatureVectors

We could not extract at least a single feature vector from the provided images to perform a face enrollment. Please refer to the quality check results of the images, which should contain failed results for the performed quality checks:

• FaceFound: Check for at least one found face.
• SingleFaceOnImage: Check for exactly one found face.
• FaceFeaturesAvailable: Check for extractable face features.

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.