IBioIDWebService.Identify Method Documentation

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

[OperationContract]
[FaultContract(typeof(BioIDWebServiceFault)]
bool Identify( BiometricClassID partition, Sample [] samples, ClassificationFlags flags, int maxResults, out ScoredClass [] matches, out string messages );
    

Parameters

partition
The BiometricClassID that specifies the storage and partition of the classes that shall be used for the identification (the ClassID is unused).
samples
The array of Samples to use for the identification. The array may contain samples of different traits.
flags
A combination of available ClassificationFlags.
maxResults
The maximum number of matches that shall be returned in the matches array.
matches
Returns a sorted array of biometric class IDs (together with a score) representing the individuals that have been identified.
messages
Returns an XML-string containing information about the identification process (see BWSMessages).

Returns true when the identification succeeded; false otherwise or when errors occurred (see messages for details).

Remarks

A biometric identification tests the given samples against all samples (biometric templates) stored in the the specified partition of the cloud storage. A list of identified BCIDs (Biometric Class IDs) is generated and sorted according to the score (a kind of probability of similarity) that has been calculated for each BCID. Note that only those BCIDs are considered that have a biometric template available for each trait specified by the delivered samples.

This method now supports live detection (currently only for the face trait). To activate live detection, simply use the flag ClassificationFlags.LiveFaceDetection with the flags parameter. Note that in this case the identification will only succeed, when it can undoubtedly determine that the given data is live data. In case that the live detection for the face trait succeeds, the degree of the head rotation between two subsequent images is reported with the returned messages XML-string.

Internally this operation performs a QualityCheck (in BioID ExtractTokenData mode) for all submitted samples before they are forwarded to the live detection - in case a live-detection flag is set - and finally the identification is performed. Therefore you might get results from these operations as well together with the identification results.

This API has a fault contract of type BioIDWebServiceFault, which is used for fatal errors like invalid arguments or missing service, etc. Messages, even error messages, generated by the identification procedure are reported via the messages output value, which contains an XML string according to the BWSMessages schema namespace.

Faults

InvalidArgument
The given partition is null or no samples have been transmitted.
AccessDenied
Access to the requested service operation has been denied. Please ensure that you use a valid client authentication certificate and that this certificate has been announced to BioID GmbH as your client certificate.
NotSupported
This service is not configured to support identification for the storage and/or partition specified by the given partition or a feature has been requested (e.g. live-detection) that is not supported by this service instance.
InternalError
For some reason BioID is not running or not configured correctly on this BWS deployment.

Operation Error-codes

The messages output XML string might contain operation specific errors as follows:

ExecutionOfJobTimedOut
The service could not process the requested task in a reasonable amount of time.
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 samples available for a specific trait to continue the verification. It seems that all samples for the trait have been removed for some reason.

Sample Error-codes

The messages output XML string might also contain errors for the individual samples. Many of the errors can result from the initial quality-check that is performed before anything else is done. Please refer to the QualityCheck method for a list of sample errors that might have been generated by the quality-check.

Additionally the following errors can occur. With any of theses errors the sample is marked as unsuitable and is not considered in the identification process:

LiveDetectionFailed
The sample has been discarded as it cannot be proven that it has been recorded from a live person.
ChallengeResponseFailed
The sample has been discarded as it does not fulfill the challenge-response criteria.
IdenticalImages
The sample has been discarded as it is identical to the previous one.