JSON Web API Verify

Performs a one-to-one comparison of the uploaded face image with a stored biometric template in order to verify whether the individual is the person he or she claims to be.

Request

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

Path Parameter

classId

The unique class ID of the person to verify. The class ID is a 64-bit positive number, managed by the client. This ID, together with the configured storage name and a partition ID will make up the Biometric Class ID (BCID), which is used to load the biometric face template to compare the given image with.

Request Body

The HTTP request body contains the image to verify.

Content type: application/json

{
  "image": "string"
}

The base64 encoded facial image to verify.

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
  },
  "verified": true,
  "score": 0
}

On success the API returns an Verification 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.

verified

Verification decision made by BWS. Set to true, when the person specified by the given class ID could have been verified successfully with the given sample; false otherwise, or when errors occurred (see errors for details).

score

The calculated verification score (a value between 0.0 and 1.0) that led to the verified decision. The higher the score, the more likely the face in the image and the template referenced by the class ID belong to the same person.

Although we use a normed score here, this score is based on the model used to create the referenced biometric template. Therefore we advise against using it for decision-making.

BWS Errors

In case that the verified field is set to false, some errors might have been reported:

FaceNotFound

No suitable face was found in the provided image.

MultipleFacesFound

More than one face has been found in the provided image.

ThumbnailExtractionFailed

The found face could not be extracted, typically because it is too close to the edge.

HTTP Status Codes

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

200 (OK)

The response body contains the Verification 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.

404 (NotFound)

A biometric face template for the given class ID does not exist.

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.