BWS Upload Web API Documentation

POST https://{bws-instance}.bioid.com/extension/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.

Important Note: The upload might take a long time if the user has a slow internet connection!
Assume a grayscale PNG image with a size of 360 x 480 pixel. This equates to a base64 encoded upload size of 226 Kbytes. Now if you take a slow upload speed of 200 Kbit per second, it takes about 9 seconds to upload this image and with 500 Kbit/s 3.5 seconds which is still too much. Starting with a 1 Mbit/s upload speed (a typical 16000 Kbit/s DSL line) it takes an acceptable amount of time, 1.8 seconds, and with 2 Mbit/s less than 1 second to upload the image.

Therefore we highly recommend to consider the following when uploading images:

  • Convert the image to grayscale before uploading it. This reduces the size of the image to about one third.
  • Use a lossless compression algorithm for the image if possible.
  • Use an aspect ratio of 3 : 4, i.e. we recommend to crop the captured images to be higher than wide as BWS internally works on 3 : 4 images. (Example: With a 640 x 480 camera, if you remove areas to the left and the right so that you get a 360 x 480 image, you reduce the upload size by nearly 50%.) Note that if you crop the image ensure that the head of the person is within the cropped area.
  • We recommend an image height of 480 pixel for enrollment and an image height of at least 320 pixel for verification (using an image size of 240 x 320 reduces the upload size again by more than 50%). Note when using those low resolutions ensure that the users face covers most of the image.

Request Information

Parameters

tag
An optional tag that describes some kind of demand or characteristics of the sample. For example: if a live-detection with challenge-response shall be performed on a face 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 when used with 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.

Request Body Format

Sample Data-Url:
data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAWgAAAHgCAAAAACtbai8AAAAK3RFWHRDcmVhdGl
vbiBUaW1lAFNhdCwgMDYgSnVsIDIwMTMgMTI6MDU6MDIgR01Ur.....kmwH6EuNQiJQAAAABJRU5ErkJggg=="

Authentication

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 BWS Token Web API.

Response Information

The Upload Web API returns an UploadResult object generated by a call to the BWS QualityCheck 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 QualityCheck reference.

Response Body Format

Accepted UploadResult Sample:
{ 
  "Accepted": true, 
  "Warnings": [ "ImageTooSmall", "ImageTooBlurry" ]
}
Refused UploadResult Sample:
{ 
  "Accepted": false, 
  "Error": "NoFaceFound",
}
Accepted UploadResult Sample
<UploadResult xmlns:i="http://www.w3.org/2001/XMLSchema-instance" xmlns="http://schemas.bioid.com/2011/12/bws">
  <Accepted>true</Accepted>
  <Warnings xmlns:d2p1="http://schemas.microsoft.com/2003/10/Serialization/Arrays">
    <d2p1:string>ImageTooSmall</d2p1:string>
    <d2p1:string>FaceAsymmetry</d2p1:string>
  </Warnings>
<UploadResult>
Refused UploadResult Sample
<UploadResult xmlns:i="http://www.w3.org/2001/XMLSchema-instance" xmlns="http://schemas.bioid.com/2011/12/bws">
  <Accepted>false</Accepted>
  <Error>MultipleFacesFound</Error>
  <Warnings xmlns:d2p1="http://schemas.microsoft.com/2003/10/Serialization/Arrays">
    <d2p1:string>BadImageBrightness</d2p1:string>
  </Warnings>
<UploadResult>

Response HTTP Status Codes

The call returns one of the standard HTTP status codes. With the success code (200) you receive the UploadResult object in the body text. With erroneous codes you typically receive a Message field within the body text describing the error. 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

JQuery sample code to upload an image, that has been drawn into an HTML5 canvas:
// get the image
var dataURL = canvas.toDataURL(); // or "bws.toGrayDataURL(canvas)" (see bws.capture.js)
// perform the Ajax request 
var jqxhr = $.ajax({
  type: "POST",
  url: "https://bws.bioid.com/extension/upload?tag=up",
  data: dataURL,
  headers: { "Authorization": "Bearer " + token } // authentication header
}).done(function (data, textStatus, jqXHR) {
  if (data.Accepted) {
    console.log('upload succeeded', data.Warnings);
  } else {
    console.log('upload error', data.Error);
  }
}).fail(function (jqXHR, textStatus, errorThrown) {
  console.log('upload failed', textStatus, errorThrown, jqXHR.responseText);
});