LiveDetection Web API
Performs a face liveness detection on two images, see Face Liveness Detection.
To perform a live detection, exactly two live recorded images are required. These are sent to the quality-check where, among other things, the face detection is done. If the images are suitable, the live-detection is executed.
To perform a live detection with challenge-response, please use the LivenessDetection API or one of the methods
This API call requires Basic Authentication, i.e. you have to provide an HTTP authorization header using the authorization method Basic and the base64 encoded string
App-ID:App-Secret. To receive the necessary BWS WebAPI access data (
App-Secret) you have to register your application on the BWS Portal first. This requires a valid BWS subscription.
This API has no required parameters. An optional
state parameter can be provided, which is then simply passed through to the BWS log and to the returned object.
or using the application/x-www-form-urlencoded media type:
If all two provided images could be processed successfully, this method returns the OK HTTP status code (200) with
false in the body content, indicating whether the submitted images prove that they are recorded from a live person or not.
state argument has also been provided, a result object is returned instead, that primarily contains the flag Success, which indicates, whether the live detection succeeded or not:
|Boolean flag indicating whether the submitted images prove that they are recorded from a live person.|
|A unique ID to identify this LiveDetection job with the BWS log.|
|The provided status string that is also added to the BWS log.|
|A list of reported (liveness detection) errors.|
|Array of quality check and liveness detection results for the provided live images.|
|List of problems detected with this live image.|
|Coordinates of the left and right eye centers, if a face was found.|
An example result object might look as follows:
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:
|IdenticalImages||The sample has been discarded as it is identical to a previous one.|
|UnsuitableImage||The face is not fully visible in the image.|
|UnnaturalMotionDetected||The 3D detector observed some unnatural motion.|
In case something goes wrong, an error HTTP status code is returned together with some additional information if available.
Response HTTP Status Codes
The call returns one of the standard HTTP status codes:
|200 OK||The response body contains a boolean value or 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 |
|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 |
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.