SOAP Method Enroll

Performs the enrollment of an individual, by calculating and storing a biometric template for each trait represented by the given samples.

[OperationContract]
[FaultContract(typeof(BioIDWebServiceFault)]
bool Enroll(BiometricClassID classId, Sample [] samples, EnrollmentFlags flags, out string messages);

Parameters

classId The BiometricClassID of the individual, that shall be enrolled. The Storage within this class ID must exist, but the Partition and/or ClassID can be unused yet, in which case the new class is created. Otherwise, the class is re-enrolled or enrolled anew, depending on the samples submitted.
samples The array of Samples to use for the enrollment. The array may contain samples of different traits.
flags A combination of available EnrollmentFlags.
messages Returns an XML-string containing information about the enrollment process (see BWSMessages).


Returns true when the enrollment procedure finished successfully for all given samples, i.e. not a single error occurred. As soon as a sample has been refused, false is returned, even if the generation of the template(s) succeeded. You have to refer to the messages for details in this case.

Note: the returned messages string also contains boolean flags for each trait that indicate, whether a template for the corresponding trait is available or not!

Remarks

The enrollment method simultaneously trains all given samples, which can even represent multiple traits, e.g. face, periocular and voice samples. The training creates a so called biometric Template for each trait specified by the given samples, which can later on be used for verification and identification purposes.

Even if there are no samples given for a single trait, it is re-trained in case a template is already associated with the given classId for this trait. This allows the re-generation of the templates after the stored data has been modified for any reason, e.g. when already trained sample-data is removed from the storage.

This method also supports liveness detection. To activate live detection, simply use the flag EnrollmentFlags.LiveFaceDetection or EnrollmentFlags.LivePeriocularDetection with the flags parameter. Note that in this case the enrollment will only succeed, when it can undoubtedly determine that the given data is live data. In case that the liveness detection for the face or the periocular 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 liveness detection - in case a live-detection flag is set - and finally the enrollment is performed. Therefore you might get results from these operations as well together with the enrollment 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 enrollment procedure are reported via the messages output value, which contains an XML string according to the BWSMessages schema namespace.

Faults

InvalidArgument The given classId is null.
AccessDenied Access to the requested service operation has been denied. Please ensure that you have specified a valid classId and you use a valid client authentication certificate and that this certificate has been announced to BioID GmbH as your client certificate.
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:

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


The following errors are typically internal problems that are not intended to be explicitly handled by clients.

DecodeSampleFailed Cannot decode image or audio sample data loaded from the storage.
TrainingFailed Not enough data available to generate a template for a specific trait.

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 enrollment 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.
FeatureExtractionFailed No features could be extracted from the sample. (This is typically an internal error.)