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.

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:

LiveDetectionFailedThe submitted samples do not prove that they are recorded from a live person.
ChallengeResponseFailedThe submitted samples do not prove that they are recorded from a live person as they do not fulfill the challenge-response criteria.
NotEnoughSamplesNot enough valid samples have been provided.
ExecutionOfJobTimedOutServer 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 OKThe response body contains the LivenessDetectionResult object.
400 Bad RequestNo samples have been uploaded.
401 UnauthorizedNo 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 ForbiddenThe number of allowed liveness detection attempts with this token has been exceeded.
500 Internal Server ErrorA server side exception occurred.

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.