LivenessDetection Web API

GET /livenessdetection

Performs a liveness detection on the previously uploaded samples (see Upload Web API) that are associated with the token provided for authorization.

The samples are fetched from the BWS storage (and removed from the storage so that they cannot be used for any other purpose) and sent to the live data detection procedure.

Implementation Note

You need to send two images in between which the user has moved slightly. Therefore, please implement the following:

Capture the first image with the person looking straight at the camera.
Use our BioID Motion Detection to automatically trigger the capturing of the second image as soon as the person has turned their head far enough.
Please get your users to perform this movement. Otherwise liveness detection fails automatically.

Request Information

Authentication

This API call requires BWS Token Authentication, i.e. you have to provide an HTTP authorization header using the authorization method Bearer (for compatibility issues you can also use the JWT identifier) and a previously issued BWS token, which can be requested using the Token Web API.

Response Information

The LivenessDetection Web API returns a LivenessDetectionResult object, that contains the flag Success, which indicates, whether the liveness detection succeeded or not. In case that the liveness detection failed, an Error is reported:

LiveDetectionFailed

The submitted samples do not prove that they are recorded from a live person.
ChallengeResponseFailed

The submitted samples do not prove that they are recorded from a live person as they do not fulfill the challenge-response criteria.
NotEnoughSamples

Not enough valid samples have been provided.
ExecutionOfJobTimedOut

Server seems to be too busy.

application/json, text/json

Successful LivenessDetectionResult Sample:
{
  "Success": true,
}

Failed LivenessDetectionResult Sample:
{
  "Success": false,
  "Error": "ChallengeResponseFailed"
}

The call returns one of the standard HTTP status codes. With the success code (200) you receive the LivenessDetectionResult object in the body text. With erroneous codes you typically get a Message field within the body text describing the error. The most commonly returned codes are:

200 OK

The response body contains the LivenessDetectionResult object.
400 Bad Request

No samples have been uploaded.
401 Unauthorized

No or an invalid authentication header has been specified. This call requires JWT Bearer Token Authentication. If a BWS token has been passed, this error typically indicates that the token has expired.
403 Forbidden

The number of allowed liveness detection attempts with this token has been exceeded.
500 Internal Server Error

A server side exception occurred.

Browse docs