Identify Web API

GET /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 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 liveness detection determined that the given data is live data (or liveness 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 explicitly switch on live data detection.

  When set to true or if the provided BWS token requires liveness detection the operation typically fails as soon as it cannot undoubtedly determine that the given data is live data. Note that for liveness detection to work at least two face- or periocular-samples need to be uploaded.

  No live data detection will be performed if the token does not require liveness 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.

Response Information

The Identify Web API returns a IdentifyResult object that contains the flag Success, which 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.

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"
}

Sample Code

• C#
• jQuery
• Java

private static async Task<bool> IdentifyAsync(string bwsToken)
{
    using (var client = new HttpClient())
    {
        client.DefaultRequestHeaders.Authorization = new AuthenticationHeaderValue("Bearer", bwsToken);
        using (var response = await client.GetAsync(ENDPOINT + $"identify"))
        {
        Console.Write("Identification response... ");
            if (response.StatusCode == HttpStatusCode.OK)
            {
                string result = await response.Content.ReadAsStringAsync();
                var json = JObject.Parse(result);
                bool success = (bool)json["Success"];
                Console.Write("Success: " + success);

            if (!success)
                {
                    // read out the error
                    string error = (string)json["Error"];
                    Console.WriteLine(" - Error: " + error);
                }
                return success;
            }

            Console.WriteLine(response.StatusCode.ToString());
            return false;
        }
    }
}

jQuery.ajax({
    url: "https://bws.bioid.com/extension/identify",
    type: "GET",
    headers: {
        "Authorization": "Bearer " + token,
    },
}).done(function(data, textStatus, jqXHR) {
    if (data.Success) {
        console.log("identification succeeded");
    } else {
        console.log("identification failed", data.Error);
    }
});

// using OkHttpClient from the OkHttp library
Request request = new Request.Builder()
        .url("https://bws.bioid.com/extension/identify")
        .addHeader("Authorization", "Bearer " + token)
        .build();
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("Success")) {
        System.out.println("identify succeeded");
    } else {
        System.out.println("identify failed: " + json.getString("Error"));
    }
}

For a complete sample refer to the walkthrough.