SOAP Message Schema Messages

The schema-namespace for the XML-messages returned by the BWS operations Enroll, Verify, Identify, LivenessDetection and QualityCheck currently is http://schemas.bioid.com/2012/02/BWSMessages (XSD file).

Such an XML-message contains information about the performed operation itself, such as a unique ID, a flag indicating whether the operation succeeded and a list of operation specific errors. It also contains information about each sample that has been received by the operation, including sample specific errors that might have occurred. The XML-structure of the message, starting with the root element OperationResults is as follows:

JobID contains a so called GUID that uniquely identifies the operation to which this message belongs. Using this ID, the operation can later be identified, for example in the monthly settlement.
Command names the executed operation.
Succeeded simply repeats the return-value of the operation.
Face is a boolean value that is only set by the enrollment operation indicating whether a template for the trait face is available or not.
Periocular is a boolean value that is only set by the enrollment operation indicating whether a template for the trait periocular is available or not.
Voice is a boolean value that is only set by the enrollment operation indicating whether a template for the trait voice is available or not.
AccuracyLevel is only reported with the PhotoVerify operation and contains the actual level of accuracy (1 - 5) the specified photo would comply with; 0 if the photo is to be rejected.
Samples lists all samples received by the operation:
- Sample describes a single sample in the samples collection by providing a
  - Trait attribute, specifying the trait (Face, Periocular or Voice) the sample belongs to, and a
  - Suitalble attribute, a flag indicating whether this sample was suitable for the operation. If set to false, a list of errors follows:
  - Errors lists sample specific errors if Suitable is set to false or warnings in case Suitable is set to true:
    - Error describes a single error by providing a
      - Code a string identifying the error, the error-
      - Message itself, and some optional
      - Details which might describe the error message a bit more.
  - Tags is an optional element that contains tags typically associated with Face or Periocular samples in case that exactly one face has been found:
    - RightEye providing in its attributes X and Y the cartesian coordinates of the right iris center (or eye center if iris was not found).
    - LeftEye providing in its attributes X and Y the cartesian coordinates of the left iris center (or eye center if iris was not found).
    - HeadMovementDirection reports the degree of head rotation between the previous image sample and this image sample. It is calculated by the photo fake defender (as used with the LivenessDetection API or with the Verify, Identify and Enroll API calls when the LiveFaceDetection or LivePeriocularDetection flag is set). Valid values are between 0 and 359 degrees.
  - FoundFaces is an optional element only available with Face or Periocular samples in case that multiple faces have been found (i.e. no Tags element is provided):
    - RightEye providing in its attributes X and Y the cartesian coordinates of the right iris center (or eye center if iris was not found).
    - LeftEye providing in its attributes X and Y the cartesian coordinates of the left iris center (or eye center if iris was not found).
Errors lists non sample specific errors as reported by the operation:
- Error describes a single error by providing a
  - Code a string identifying the error, the error
  - Message itself, and some optional
  - Details which might describe the error message a bit more.
Statistics contains some statistical informations about the performed operation:
- ProcessingTime shows the amount of time that was needed to perform the operation.
- TotalServiceTime shows the total amount of time the server needed to service the operation.

The parsing of such an XML-message string is very simple. Here is an example of how to do it in C#:

// lets parse the message string 'messages' as it might have been returned
// by a call to Enroll, Verify, Identify or QualityCheck:
using (XmlReader reader = XmlReader.Create(new StringReader(messages)))
{
    var serializer = new XmlSerializer(typeof(JobResult), "http://schemas.bioid.com/2012/02/BWSMessages");
    var result = (JobResult)serializer.Deserialize(reader);
}
// these are the classes we use for the deserialization:
[XmlRoot(ElementName = "OperationResults", Namespace = "http://schemas.bioid.com/2012/02/BWSMessages")]
public class JobResult
{
    public Guid JobID { get; set; }
    public string Command { get; set; }
    public bool Succeeded { get; set; }
    public bool? Face { get; set; }
    public bool? Periocular { get; set; }
    public bool? Voice { get; set; }
    public List<JobSample> Samples { get; set; }
    public List<JobMessage> Errors { get; set; }
    public JobStatistics Statistics { get; set; }
}
[XmlType(TypeName = "Sample")]
public class JobSample
{
    [XmlAttribute]
    public Trait Trait { get; set; }
    [XmlAttribute]
    public bool Suitable { get; set; }
    public List<JobMessage> Errors { get; set; }
    public SampleTags Tags { get; set; }
    public List<EyeCoordinates> FoundFaces { get; set; }
}
[XmlType(TypeName = "Error")]
public class JobMessage
{
    public string Code { get; set; }
    public string Message { get; set; }
    public string Details { get; set; }
}
[XmlType(TypeName = "Tags")]
public class SampleTags
{
    public Cartesian RightEye { get; set; }
    public Cartesian LeftEye { get; set; }
    public int? HeadMovementDirection { get; set; }
}
public class EyeCoordinates
{
    public Cartesian RightEye { get; set; }
    public Cartesian LeftEye { get; set; }
}
public struct Cartesian
{
    [XmlAttribute]
    public double X { get; set; }
    [XmlAttribute]
    public double Y { get; set; }
}
[XmlType(TypeName = "Statistics")]
public class JobStatistics
{
    public DateTime ProcessingTime { get; set; }
    public DateTime TotalServiceTime { get; set; }
}

Browse docs

SOAP Message Schema Messages