Playground biometrics demo BioID home page

Upload Web API

POST /upload

The Upload Web API is used for the asynchronous upload of different media samples that are associated with a token and can later be used for various biometric operations.

When the API receives a sample, it automatically performs a quality-check. When the quality check succeeds, e.g. when exactly one face has been found in an image, the sample is placed in the BWS storage and associated with the token that has been used for the authorization of this API call.

Request Information

  • Parameters

  • tag
    An optional tag that describes some kind of demand or characteristics of the sample. For example: if a liveness detection with challenge-response shall be performed on a face or periocular sample, the expected head movement direction can be specified with this tag using one or more of the values up, down, left and right.
  • index
    An optional index within a sequence of uploaded samples. If given it is only used to sort the uploaded samples in the order they are intended to be (important for challenge-response).
  • trait
    Optionally overwrite of default trait-handling: images are associated with the face trait, audio data is associated with the voice trait. For example, the string "Face, Periocular" can be used to associate a single uploaded image with the face and the periocular trait.
  • dataURL
    A single media sample, encoded into a Data-URL using the data URI scheme as described in RFC 2397 (see also at Wikipedia).
    Send this parameter in the request body.


Response Information

The Upload Web API returns an UploadResult object generated by a call to the BWS quality check method. The returned object contains the flag Accepted that indicates whether the sample has passed the quality-check or not. If the sample has not been accepted an appropriate Error is reported depending on the trait of the uploaded sample, e.g. NoFaceFound or MultipleFacesFound for face samples or BadSignalQuality or AudioSignalTooShort for voice samples. In any case some additional Warnings may be included in an array of Sample Error-codes as described in the quality check reference.

Return values of API calls are standard HTTP status codes. With the success code (200) you receive the issued BWS token in the body text. With error codes a Message field within the body text describing the error is returned. The most commonly return codes are:
  • 200 OK
    The response body contains the UploadResult object.
  • 400 Bad Request
    Invalid sample data has been uploaded or the sample format is unsupported.
  • 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.
  • 500 Internal Server Error
    A server side exception occurred.

Sample Code

private static async Task<bool> UploadAsync(string bwsToken, string dataUrlImage)
    using (var client = new HttpClient())
        client.DefaultRequestHeaders.Authorization = new AuthenticationHeaderValue("Bearer", bwsToken);
        using (var content = new StringContent(dataUrlImage))
        using (var response = await client.PostAsync(ENDPOINT + $"upload", content))
            Console.Write("Uploading image... ");
            if (response.StatusCode == HttpStatusCode.OK)
                string result = await response.Content.ReadAsStringAsync();
                var json = JObject.Parse(result);
                bool accepted = (bool)json["Accepted"];
                string error = (string)json["Error"];
                if (!string.IsNullOrEmpty(error)) { Console.WriteLine(error);  }
                var warnings = json["Warnings"];
                return accepted;

              return false;
const dataURL = canvas.toDataURL();  // or "bws.toGrayDataURL(canvas)" (see bws.capture.js)
    url: "" + jQuery.param({
        "tag": "up"
    type: "POST",
    headers: {
        "Authorization": "Bearer " + token
    data: dataURL,
}).done(function (data, textStatus, jqXHR) {
  if (data.Accepted) {
    console.log("upload succeeded", data.Warnings);
  } else {
    console.log("upload error", data.Error);
// using OkHttpClient from the OkHttp library
HttpUrl url = HttpUrl.parse("").newBuilder()
        .addQueryParameter("trait", "face")
Request request = new Request.Builder()
        .addHeader("Authorization", "Bearer " + token)
        .post(RequestBody.create(MediaType.parse("text/plain"), "data:image/png;base64," + Base64.getEncoder().encodeToString(getPngAsByteArray())))
OkHttpClient client = new OkHttpClient();
Response response = client.newCall(request).execute();
if (response.code() == 200) {
    // using org.json.JSONObject from JSON-java library
    JSONObject json = new JSONObject(response.body().string());
    if (json.getBoolean("Accepted")) {
        System.out.println("upload succeeded");

For a complete sample refer to the walkthrough.