BWS Result Web API Documentation

GET https://{bws-instance}.bioid.com/extension/result?access_token={token}

Fetches the result of the last biometric operation (i.e. verification, identification or enrollment) performed with the token provided. Typically this is necessary if the token has been transmitted to another application to perform the biometric task and you now want to know what the result has been. An example for this procedure is the BWS unified user interface.

Request Information

Parameters

access_token
Required. The BWS web token that was used to perform the biometric task.

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.

You should use the same authentication information as it was used to request the token with the Token Web API, as the API will verify whether the token matches the application identified by this authentication information.

Response Information

The Result Web API returns an OperationResult object describing the result of the last biometric operation. The operation itself is in the Action element, the Biometric Class ID of the involved user or partition in the BCID field. The Success flag indicates whether the operation succeeded or not. In case that the operation failed (i.e. Success is set to false) an error is reported:

null (i.e no error)
In the case of a verification operation this simply indicates that the user has not been recognized. Enrollment should always report an error if the operation failes.
LiveDetectionFailed
The submitted samples do not prove that they are recorded from a live person.
ChallengeResponseFailed
The submitted samples do not prove that they are recorded from a live person as they do not fulfill the challenge-response criteria.
NoTemplateAvailable
The user has not been enrolled yet.
NotEnoughSamples
Not enough valid samples have been provided.
ExecutionOfJobTimedOut
Server seems to be too busy.

In case that the operation was an identification, a sorted array of BCIDs together with their scores is returned in the Matches element, containing a list of BCID and Score elements.

Response Body Format

Successful OperationResult Sample:
{ 
  "Action": "enrollment",
  "BCID": "bioid/9876/12345",
  "Success": true, 
}
Successful OperationResult Sample:
{ 
  "Action": "identification",
  "BCID": "bioid/9876/0",
  "Success": true, 
  "Matches":[{"BCID":"bioid/9876/12345","Score":0.73721338244277179},{"BCID":"bioid/9876/54321","Score":0.4841065082191604},...]
}
Failed OperationResult Sample:
{ 
  "Action": "verification",
  "BCID": "bioid/9876/12345",
  "Success": false, 
  "Error": "NoTemplateAvailable"
}
Successful OperationResult Sample
<OperationResult xmlns:i="http://www.w3.org/2001/XMLSchema-instance" xmlns="http://schemas.bioid.com/2011/12/bws">
  <Action>enrollment</Action>
  <BCID>bioid/9876/12345</BCID>
  <Success>true</Success>
</OperationResult>
Successful OperationResult Sample
<OperationResult xmlns:i="http://www.w3.org/2001/XMLSchema-instance" xmlns="http://schemas.bioid.com/2011/12/bws">
  <Action>identification</Action>
  <BCID>bioid/9876/0</BCID>
  <Success>true</Success>
  <Matches>
    <ScoredBCID><BCID>bioid/9876/12345</BCID><Score>0.73721338244277179</Score></ScoredBCID>
    <ScoredBCID><BCID>bioid/9876/54321</BCID><Score>0.4841065082191604</Score></ScoredBCID>
    ...
  </Matches>
</OperationResult>
Failed OperationResult Sample
<OperationResult xmlns:i="http://www.w3.org/2001/XMLSchema-instance" xmlns="http://schemas.bioid.com/2011/12/bws">
  <Action>verification</Action>
  <BCID>bioid/9876/12345</BCID>
  <Success>false</Success>
  <Error>NoTemplateAvailable</Error>
</OperationResult>

Response HTTP Status Codes

The call returns one of the standard HTTP status codes. With the success code (200) you receive the described OperationResult object in the body text. With erroneous codes you typically get a Message field within the body text describing the error. The most commonly returned codes are:

200 OK
The response body contains the OperationResult object.
204 No Content
No result has been logged for the specified token.
400 Bad Request
No or an invalid token has been specified.
401 Unauthorized
No or an invalid authentication header has been specified.
500 Internal Server Error
A server side exception occurred.

Sample code

ASP.NET MVC 4 C# sample code to fetch the result from the last BWS operation in the BWS unified user interface callback:
public ActionResult BWSCallback(string access_token, string state, string error)
{
  // sample view model to store results to be displayed in the view
  BWSCallbackModel model = new BWSCallbackModel();
  if (!string.IsNullOrWhiteSpace(error))
  {
    // an error occurred on the BWS user interface, e.g. user_abort ...
    model.GuiError = error;
  }
  // ask the BWS Web API for the result
  try
  {
    var httpClient = new HttpClient();
    // requires Authentication
    httpClient.DefaultRequestHeaders.Authorization = new AuthenticationHeaderValue("Basic", 
      Convert.ToBase64String(Encoding.GetEncoding("iso-8859-1").GetBytes("sample.app.bioid.com:Sample-App-Secret")));
    // call the BWS Result Web API at bws.bioid.com
    var response = httpClient.GetAsync(
      string.Format("https://bws.bioid.com/extension/result?access_token={0}", access_token)).Result;
    Stream responseStream = response.Content.ReadAsStreamAsync().Result;
    if (response.StatusCode == System.Net.HttpStatusCode.OK)
    {
      var json = JObject.Load(new JsonTextReader(new StreamReader(responseStream)));
      model.Success = (bool)json["Success"];
      model.BCID = (string)json["BCID"];
      model.Action = (string)json["Action"];
      model.Error = (string)json["Error"];
      if(model.Success)
      {
        // user has been verified or enrolled successfully, do what needed here...
      }
      // else: user has not been recognized or enrollment failed
    }
    else if (response.StatusCode == System.Net.HttpStatusCode.NoContent)
    {
      model.Error = "You have not performed any biometric action.";
    }
    else if(responseStream.Length > 0)
    {
      var json = JObject.Load(new JsonTextReader(new StreamReader(responseStream)));
      model.Error = (string)json["Message"]; // typically contains an error message
    }
  }
  catch (Exception ex)
  {
    model.Error = string.Format("Error: {0}", ex.Message);
  }
  return View(model);
}