Playground biometrics demo BioID home page

PassiveLiveDetection Web API

POST /passivelivedetection

Performs a passive face liveness detection (see Face Liveness Detection) on a single image.

To perform a passive live detection, only one live recorded image is required. The image is sent to the quality-check where, among other things, the face detection is done. If the image is suitable, the passive live-detection is executed.

Request Information

  • Parameters

  • This API has no required parameters. An optional state parameter can be provided which is simply passed through to the BWS log and to the returned object.

The body contains a single image media sample, encoded into a Data-URL using the data URI scheme as described in  RFC 2397 (see also at Wikipedia).

Response Information

This API returns a LiveDetectionResult result object is returned, that primarily contains the flag Success, which indicates, whether the live detection succeeded or not:

  • Success
    Boolean flag indicating whether the submitted images prove that it is recorded from a live person.
  • JobID
    A unique ID to identify this LiveDetection job with the BWS log.
  • State
    An optional provided status string that is also added to the BWS log.
  • Errors
    A list of reported (liveness detection) errors.
  • Samples
    Array of quality check and liveness detection results for the provided live images.
  • Errors
    List of problems detected with this live image.
  • EyeCenters
    Coordinates of the left and right eye centers, if a face was found.

The reported sample-errors typically come from the quality-check, which is performed for each sample (refer to the SOAP Quality Check API for a list of possible error-codes), or from the live detection, that might report additional errors as follows:

  • UnsuitableImage
    The face is not fully visible in the image.

In case something goes wrong, an error HTTP status code is returned together with some additional information if available.


The call returns one of the standard HTTP status codes:

  • 200 OK
    The response body contains the result object as described above.
  • 400 Bad Request

    Invalid samples have been uploaded or they could not be processed successfully, e.g. no face found, etc. The response body typically has a Message field containing the error code:

    • "InvalidSampleData": The submitted samples could not be decoded into images.
    • One of the error codes as generated by a Quality Check.
  • 401 Unauthorized
    Basic Authentication is required.
  • 415 Unsupported Media Type
    You probably forgot to specify the media type, e. g. application/json.
  • 500 Internal Server Error
    A server side exception occurred. The content may contain a Message and an ExceptionMessage.