Result Web API

GET /result?access_token={token}


Fetches the result of the last biometric operation (i.e. verificationidentificationenrollment or liveness detection) 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 unified user interface.

Request Information

Parameters

access_tokenRequired. 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 fails.
LiveDetectionFailedThe submitted samples do not prove that they are recorded from a live person.
ChallengeResponseFailedThe submitted samples do not prove that they are recorded from a live person as they do not fulfill the challenge-response criteria.
NoTemplateAvailableThe user has not yet been enrolled.
NotEnoughSamplesNot enough valid samples have been provided.
ExecutionOfJobTimedOutServer 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

application/json, text/json
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"
}

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 OKThe response body contains the OperationResult object.
204 No ContentNo result has been logged for the specified token.
400 Bad RequestNo or an invalid token has been specified.
401 UnauthorizedNo or an invalid authentication header has been specified.
500 Internal Server ErrorA server side exception occurred.

Sample Code

private static async Task<string> ResultAsync(string bwsToken)
{
	using (var client = new HttpClient())
	{
		client.DefaultRequestHeaders.Authorization = new AuthenticationHeaderValue("Basic", Convert.ToBase64String(Encoding.ASCII.GetBytes($"{APP_IDENTIFIER}:{APP_SECRET}")));
		using (var response = await client.GetAsync(ENDPOINT + $"result?access_token={bwsToken}"))
		{
			Console.Write("Result response... ");
			if (response.StatusCode == HttpStatusCode.OK)
			{
				string result = await response.Content.ReadAsStringAsync();
				var json = JObject.Parse(result);
				bool success = (bool)json["Success"];
				string action = (string)json["Action"];
				string bcid = (string)json["BCID"];

				// For identify we receive the matches
				if (action == TokenFor.identify.ToString())
				{
					// we can see the matches
					var matches = json["Matches"];

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

			Console.WriteLine(response.StatusCode.ToString());
			return string.Empty;
		}
	}
}

For a complete sample refer to the walkthrough.

// using OkHttpClient from the OkHttp library
HttpUrl url = HttpUrl.parse("https://bws.bioid.com/extension/result").newBuilder()
        .addQueryParameter("access_token", token)
        .build();
Request request = new Request.Builder()
        .url(url)
        .addHeader("Authorization", Credentials.basic(APP_IDENTIFIER, APP_SECRET))
        .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(json.getString("Action") + " succeeded");
    } else {
        System.out.println(json.getString("Action") + " failed");
    }
}