Web live detection API

POST /livedetection


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 Enroll, Verify or Identify.

Request Information

Authentication

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 (therefore the transport is secured using TLS/SSL). To receive the necessary BWS WebAPI access data (App-ID and App-Secret) you have to register your application on the BWS Management Portal first. This requires a valid BWS subscription.

Body

The body contains the two live images encoded into a Data-URL using the data URI scheme as described in RFC 2397 (see also at Wikipedia), e.g. using the application/json media type:

{
"liveimage1": "data:image...",
"liveimage2": "data:image..."
}

or using the application/x-www-form-urlencoded media type:

liveimage1=data:image...&liveimage2=data:image...

Response

If all two provided images could be processed successfully, this method returns the OK HTTP status code (200) with simply true or false in the body content, indicating whether the submitted images prove that they are recorded from a live person or not.

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 simply says true or false, indicating whether the images prove that they are recorded from a live person or not.
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:
  • "MissingData": Not all two images have been supplied.
  • "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.

Sample Code

using (var client = new HttpClient())
{
    client.DefaultRequestHeaders.Authorization = new AuthenticationHeaderValue("Basic",
        Convert.ToBase64String(Encoding.ASCII.GetBytes($"{APP_IDENTIFIER}:{APP_SECRET}")));
    string json;
    using (var img1stream = img1.OpenRead())
    using (var img2stream = img2.OpenRead())
    {
        var bfr1 = new byte[img1stream.Length];
        var bfr2 = new byte[img2stream.Length];
        await Task.WhenAll(
            Task.Run(async () => await img1stream.ReadAsync(bfr1, 0, bfr1.Length)),
            Task.Run(async () => await img2stream.ReadAsync(bfr2, 0, bfr2.Length))
        );
        json = $@"{{""liveimage1"":""data:image/png;base64,{Convert.ToBase64String(bfr1)}"""
            + $@",""liveimage2"":""data:image/png;base64,{Convert.ToBase64String(bfr2)}""}}";
    }
    using (var content = new StringContent(json, Encoding.ASCII, "application/json"))
    using (var response = await client.PostAsync(ENDPOINT + "livedetection", content))
    {
        if (response.StatusCode == HttpStatusCode.OK)
        {
            if (bool.TryParse(await response.Content.ReadAsStringAsync(), out var parsed))
            {
                return parsed;
            }
        }
        return false;
    }
}
// using org.json.JSONObject from JSON-java library
JSONObject requestBody = new JSONObject();
requestBody.put("liveimage1", "data:image/png;base64," + Base64.getEncoder().encodeToString(png1AsByteArray));
requestBody.put("liveimage2", "data:image/png;base64," + Base64.getEncoder().encodeToString(png2AsByteArray));

// using OkHttpClient from the OkHttp library
Request request = new Request.Builder()
        .url("https://bws.bioid.com/extension/livedetection")
        .addHeader("Authorization", Credentials.basic(APP_IDENTIFIER, APP_SECRET))
        .post(RequestBody.create(MediaType.parse("application/json"), requestBody.toString()))
        .build();
OkHttpClient client = new OkHttpClient();
Response response = client.newCall(request).execute();
if (response.code() == 200) {
    if (response.body().string().equals("true")) {
        System.out.println("recorded from a live person");
    } else {
        System.out.println("not recorded from a live person");
    }
}