Web LivenessDetection 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.

Request Information


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.

Response Body Format

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.