BWS Identify Web API Documentation

GET https://{bws-instance}.bioid.com/extension/identify

Performs a one-to-many comparison of the uploaded samples with stored biometric templates in order to identify the individuals that are most likely represented by the given samples.

The samples to be identified are those that have previously uploaded (see BWS Upload Web API) using the same token that has been used for the authorization of this call. These samples are fetched from the BWS storage (and removed from the storage, so that they cannot be used for any other purpose), sent to the live data detection procedure and finally, if the live detection determined that the given data is live data (or live detection is disabled) transferred to the identification procedure.

The biometric templates which are compared against the samples are taken from the storage and partition as specified by the BCID in the provided BWS token.

Request Information

Parameters

livedetection
Optional, defaults to the setting in the BWS Token. A boolean parameter to explicitely switch on live data detection.
When set to true or if the provided BWS token requires live-detection the operation typically fails as soon as it cannot undoubtedly determine that the given data is live data. Note that for live-detetcion to work at least two face-samples need to be uploaded.
No live data detection will be performed if the token does not require live-detection and this flag is set to false.
maxResults
Optional, defaults to 20. The maximum number of matches that shall be returned in the matches array, a sorted array of biometric class IDs together with their score representing the individuals that have been identified.

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 Identify Web API returns a IdentifyResult object that contains the flag Success that shows whether the identification could be performed or not. In case that the identification failed (i.e. Success is set to false) an Error is reported:

null (i.e no error)
Typically there are simply no users enrolled in the specified partition.
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.
NotEnoughSamples
Not enough valid samples have been provided.
ExecutionOfJobTimedOut
Server seems to be too busy.

Additionally a sorted array of BCIDs together with a score is returned in the Matches element, containing a list of Biometric Class IDs and Score elements.

Response Body Format

Successful IdentifyResult Sample:
{ 
  "Success": true, 
  "Matches":[
    {"Score":0.73721338244277179,"Storage":"bioid","Partition":9876,"ClassID":12345},
    {"Score":0.4841065082191604,"Storage":"bioid","Partition":9876,"ClassID":54321},
    ... ]
}
Failed IdentifyResult Sample:
{ 
  "Success": false, 
  "Error": "LiveDetectionFailed"
}
Successful IdentifyResult Sample
<IdentifyResult xmlns:i="http://www.w3.org/2001/XMLSchema-instance" xmlns="http://schemas.bioid.com/2011/12/bws">
  <Success>true</Success>
  <Matches>
    <ScoredClass><ClassID>12345</ClassID><Partition>9876</Partition><Storage>bioid</Storage><Score>0.73721338244277179</Score></ScoredClass>
    <ScoredClass><ClassID>54321</ClassID><Partition>9876</Partition><Storage>bioid</Storage><Score>0.4841065082191604</Score></ScoredClass>
    ...
  </Matches>
</IdentifyResult>
Failed IdentifyResult Sample
<IdentifyResult xmlns:i="http://www.w3.org/2001/XMLSchema-instance" xmlns="http://schemas.bioid.com/2011/12/bws">
  <Success>false</Success>
  <Error>NoTemplateAvailable</Error>
</IdentifyResult>

Response HTTP Status Codes

The call returns one of the standard HTTP status codes. With the success code (200) you receive the IdentifyResult 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 IdentifyResult object.
400 Bad Request
No samples have been uploaded.
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.
403 Forbidden
The number of allowed identification attempts with this token has been exceeded.
500 Internal Server Error
A server side exception occurred.

Sample code

JQuery sample code to identify the samples that have previously been uploaded using the same token:
var jqxhr = $.ajax({
  type: "GET",
  url: "https://bws.bioid.com/extension/identify",
  headers: { "Authorization": "Bearer " + token }
}).done(function (data, textStatus, jqXHR) {
  if (data.Success) {
    console.log('identification succeeded');
  } else {
    console.log('identification failed', data.Error);
  }
});