API reference guide

1. Introduction

This document includes the API description of the libraries provided in the product FacePhi SelphID SDK.

2. SelphID API Description (Front-end)

SelphID SDK is a set of server libraries that uses the information generated by the Widgets of FacePhi for native or web applications. As described in the following sections, some components called Widgets are provided for face capture (Selphi) and identity document capture (SelphID), which can be integrated into the front-end of any application.

2.1. Selphi Widget

Using the widget Selphi, which incorporates the mechanism for facial detection and extraction and the user's liveness, the following information can be obtained through the properties below:

• Image property: Represents the user's image with the most frontal detected facial pose.

• TemplateRaw property: Represents the tokenized biometric template of the user with the most frontal detected facial pose. This template is used to perform biometric authentication with SelphID SDK.

Note

Additionally, a tokenized functionality is provided generateTemplateRaw (see API) which allows converting an image or a data buffer into a tokenized data buffer in the form of templateRaw. This templateRaw can be used in several functionalities of SelphID SDK.

2.2. SelphID Widget

Using the widget SelphID, which incorporates the automatic document detection and capture mechanism, the following information can be obtained through the properties below:

• TokenOCR property: Represents a token (timestamp + AES256 encryption) containing the data detected in the document through the OCR performed.

• TokenFrontDocument property: Represents the tokenized image (timestamp + AES256 encryption) of the front side of the document cropped to the document edges.

• TokenBackDocument property: Represents the tokenized image (timestamp + AES256 encryption) of the back side of the document cropped to the document edges.

• TokenFaceImage property: Represents the tokenized image (timestamp + AES256 encryption) of the user's photograph on the document. This token is used to perform biometric authentication with the SDK.

• TokenRawFrontDocument property: Represents the tokenized image (timestamp + AES256 encryption) of the front side of the document without cropping to the document edges, that is, as captured by the camera.

• TokenRawBackDocument property: Represents the tokenized image (timestamp + AES256 encryption) of the back side of the document without cropping to the document edges, that is, as captured by the camera.

3. SelphID API Description (Back-end)

The API of the libraries provided in SelphID is described below, detailing the methods that the integrator can use to incorporate facial recognition, extraction of information from identity documents, and document validation functionalities.

3.1. Library Initialization

SelphIDVerifier represents the main class of the libraries, which contains all the methods available for each of the functionalities.

The initialization of the libraries can be performed in three different ways depending on the configured environment variables:

3.1.1. Initialization using the method loadWithConfigPath()

Prerequisites

Configure the environment variables and the config.cfg file (SDK configuration for On-premise installation):

• FACEPHI_SELPHID_INSTALL_PATH

• FACEPHI_SELPHID_INSTALL_BIN

• LD_LIBRARY_PATH

• PATH

public static void main(String[] args) {
  // Instantiate a SelphIDVerifier object.
  SelphIDVerifier verifier = new SelphIDVerifier();

  // Specifies the path where the configuration file is located.
  String configurationFilePath =
    "C:/Program Files/FacePhi/Sdk/SelphId/x.x.x.x/config/config.cfg";

  // Load the library indicating the path where to look for the config file.
  verifier.loadWithConfigPath(configurationFilePath);

  // Make use of the library.

  // Unload the library when you have finished.
  verifier.unload();
}

3.1.2. Initialization using the method load()

Prerequisites

Configure the environment variables and the config.cfg file (SDK configuration for On-premise installation):

• FACEPHI_SELPHID_INSTALL_PATH

• FACEPHI_SELPHID_INSTALL_BIN

• LD_LIBRARY_PATH

• PATH

It is not necessary to specify the path of the configuration file, since it will be searched automatically in the following path: FACEPHI_SELPHID_INSTALL_PATH/config/selphid.cfg

public static void main(String[] args) {
  // Instantiate a SelphIDVerifier object.
  SelphIDVerifier verifier = new SelphIDVerifier();

  // Load the library.
  verifier.load();

  // Make use of the library.

  // Unload the library when you have finished.
  verifier.unload();
}

3.1.3. Initialization using the method loadFromEnvVars()

Prerequisites

Configure the environment variables (SDK configuration for On-premise installation):

• FACEPHI_SELPHID_INSTALL_PATH

• FACEPHI_SELPHID_INSTALL_BIN

• LD_LIBRARY_PATH

• PATH

• FACEPHI_SELPHID_DEBUGPATH_KEY

• FACEPHI_SELPHID_USAGEPATH_KEY

• FACEPHI_SELPHID_FACIALLIVENESS_PATH_KEY

• FACEPHI_SELPHID_FACIAL_LICPATH_KEY

Instead of configuring the config.cfg file, these variables are set directly as environment variables.

public static void main(String[] args) {
  // Instantiate a SelphIDVerifier object.
  SelphIDVerifier verifier = new SelphIDVerifier();

  // Load the library.
  verifier.loadFromEnvVars();

  // Make use of the library.

  // Unload the library when you have finished.
  verifier.unload();
}

Important

The initialization of the libraries using the method load(), loadWithConfigPath() or loadFromEnvVars() load()

should only be performed once during the lifecycle of your application. Once all processes involving the use of these libraries are finished, it is important to release the resources associated with them;.

The unloading of the libraries using the method unload() load() Once the method unload(), it is no longer possible to perform a load().

If any condition occurs that prevents the libraries from loading correctly, an SelphIDException. To learn about the exception types, see the corresponding section 3.10. Description of SelphIDException in the provided API.

3.2. Facial extraction methods

To perform the extraction of a user's facial data, the integrator has different methods available in the class SelphIDVerifier. The integrator must use one method or another depending on the data generated on the client. The possible situations are described below.

Note

The result of these methods will always be an object SelphIDFacialExtractionResult, explained in 3.9.1. SelphIDFacialExtractionResult.

3.2.1. Facial extraction using an image

The method to use is the following:

SelphIDFacialExtractionResult r = extractFacialWithImageBuffer(
  byte[] imageBuffer,
  SelphIDVerifierOptions options
);

The steps necessary to perform facial extraction using an image are as follows (example method):

Prerequisites

• Obtain the image (base64 string) through the Image property using the Selphi widget.

• Send the image base64 string to the server.

String extractBiometricFacialTemplate(String imageBase64) {
  // Decode base64 to get the byte array corresponding to the image on the server.
  byte[] imageBuffer = Base64.getDecoder().decode(
    imageBase64.getBytes());

  // Create the SelphIDVerifierOptions and configure it if needed.
  SelphIDVerifierOptions options = new SelphIDVerifierOptions();

  // Extraction
  // Check 3.1. section to initializate SelphIDVerifier.
  SelphIDFacialExtractionResult r = verifier.extractFacialWithImageBuffer(imageBuffer, options);

  // Explore the information obtained in SelphIDFacialExtractionResult like facial position.
  Rectangle facePostion = r.getFaceRectangle();

  // Return the biometric facial template.
  return r.getFacialTemplate();
}

3.2.2. Facial extraction using a template

The method to use is the following:

SelphIDFacialExtractionResult r = extractFacialWithRawTemplate(
  byte[] rawTemplateBuffer,
  SelphIDVerifierOptions options
);

The steps necessary to perform facial extraction using a biometric template are as follows (example method):

Prerequisites

• Obtain the biometric template (base64 string) through the TemplateRaw property using the Selphi widget.

• Send the biometric template base64 string to the server.

String extractBiometricFacialTemplate(String templateRawBase64) {
  // Decode base64 to get the byte array corresponding to the template.
  byte[] rawTemplateBuffer = Base64.getDecoder().decode(
    templateRawBase64.getBytes());

  // Create the SelphIDVerifierOptions and configure it if needed.
  SelphIDVerifierOptions options = new SelphIDVerifierOptions();

  // Extraction
  // Check 3.1. section to initializate SelphIDVerifier.
  SelphIDFacialExtractionResult r = verifier.extractFacialWithRawTemplate(rawTemplateBuffer, options);

  // Explore the information obtained in SelphIDFacialExtractionResult like facial position.
  Rectangle facePostion = r.getFaceRectangle();

  // Return the biometric facial template.
  return r.getFacialTemplate();
}

3.3. Facial authentication methods

To perform a user's facial authentication, the integrator has different methods available in the class SelphIDVerifier. The integrator must use one method or another depending on the data generated on the client. Each of the possible situations is described in the following subsections.

Note

The result of these methods will always be an object SelphIDFacialAuthenticationResult, explained in 3.9.2. SelphIDFacialAuthenticationResult.

3.3.1. Facial authentication using images

SelphIDFacialAuthenticationResult r = authenticateFacialWithImageBuffers(
  byte[] imageQuery,
  byte[] imageTarget,
  SelphIDVerifierOptions options
);

The steps necessary to perform facial authentication using two images are as follows (example method):

Prerequisites

• Obtain the first image (base64 string) through the Image property using the Selphi widget.

• Obtain the second image (base64 string) through the Image property using the Selphi widget.

• Send both base64 strings to the server.

boolean isMatch(String firstImageBase64, String secondImageBase64) {
  // Decode base64 to get the byte array corresponding to each image on the server.
  byte[] imageQuery = Base64.getDecoder().decode(
    firstImageBase64.getBytes());
  byte[] imageTarget = Base64.getDecoder().decode(
    secondImageBase64.getBytes());

  // Create the SelphIDVerifierOptions and configure it if needed.
  SelphIDVerifierOptions options = new SelphIDVerifierOptions();

  // Extraction
  // Check 3.1. section to initializate SelphIDVerifier.
  SelphIDFacialAuthenticationResult r = verifier.authenticateFacialWithImageBuffers(
    imageQuery, imageTarget, options);

  // Explore the information obtained in SelphIDFacialAuthenticationResult like similarity
  float similarity = r.getSimilarity();

  // Return if images are matching
  return r.getFacialAuthenticationStatus() == FacialAuthenticationStatus.Positive;
}

3.3.2. Facial authentication using biometric templates

The method to use is the following:

SelphIDFacialAuthenticationResult r = authenticateFacialWithRawTemplates(
  byte[] templateQuery,
  byte[] templateTarget,
  SelphIDVerifierOptions options
);

The steps necessary to perform facial authentication using two biometric templates are as follows (example method):

Prerequisites

• Obtain the first biometric template (base64 string) through the TemplateRaw property using the Selphi widget.

• Obtain the second biometric template (base64 string) through the TemplateRaw property using the Selphi widget.

• Send both base64 strings to the server.

boolean isMatch(String firstTemplateRawBase64, String secondTemplateRawBase64) {
  // Decode base64 to get the byte array corresponding to each image on the server.
  byte[] templateQuery = Base64.getDecoder().decode(
    firstTemplateRawBase64.getBytes());
  byte[] templateTarget = Base64.getDecoder().decode(
    secondTemplateRawBase64.getBytes());

  // Create the SelphIDVerifierOptions and configure it if needed.
  SelphIDVerifierOptions options = new SelphIDVerifierOptions();

  // Extraction
  // Check 3.1. section to initializate SelphIDVerifier.
  SelphIDFacialAuthenticationResult r = verifier.authenticateFacialWithRawTemplates(
    templateQuery, templateTarget, options);

  // Explore the information obtained in SelphIDFacialAuthenticationResult like similarity
  float similarity = r.getSimilarity();

  // Return if images are matching
  return r.getFacialAuthenticationStatus() == FacialAuthenticationStatus.Positive;
}

3.3.3. Facial authentication using an image and a biometric template

The method to use is the following:

SelphIDFacialAuthenticationResult r = authenticateFacialWithImageRawTemplate(
  byte[] imageQuery,
  byte[] templateTarget,
  SelphIDVerifierOptions options
);

The steps necessary to perform facial authentication using an image and a biometric template are as follows (example method):

Prerequisites

• Obtain the image (base64 string) through the Image property using the Selphi widget.

• Obtain the biometric template (base64 string) through the TemplateRaw property using the Selphi widget.

• Send both base64 strings to the server.

boolean isMatch(String imageBase64, String templateRawBase64) {
  // Decode base64 to get the byte array corresponding to each image on the server.
  byte[] imageQuery = Base64.getDecoder().decode(
    imageBase64.getBytes());
  byte[] templateTarget = Base64.getDecoder().decode(
    templateRawBase64.getBytes());

  // Create the SelphIDVerifierOptions and configure it if needed.
  SelphIDVerifierOptions options = new SelphIDVerifierOptions();

  // Extraction
  // Check 3.1. section to initializate SelphIDVerifier.
  SelphIDFacialAuthenticationResult r = verifier.authenticateFacialWithImageRawTemplate(
    imageQuery, templateTarget, options);

  // Explore the information obtained in SelphIDFacialAuthenticationResult like similarity
  float similarity = r.getSimilarity();

  // Return if images are matching
  return r.getFacialAuthenticationStatus() == FacialAuthenticationStatus.Positive;
}

3.3.4. Facial authentication using the photograph on the document and an image

The method to use is the following:

SelphIDFacialAuthenticationResult r = authenticateFacialWithRawDocumentImage(
  byte[] rawDocument,
  byte[] imageTarget,
  SelphIDVerifierOptions options
);

The steps necessary to perform facial authentication using the document photograph and an image are as follows (example method):

Prerequisites

• Obtain the document photograph token (base64 string) through the TokenFaceImage property using the SelphID widget.

• Obtain the image (base64 string) through the Image property using the Selphi widget.

• Send both base64 strings to the server.

boolean isMatch(String tokenFaceImageBase64, String imageBase64) {
  // Decode base64 to get the byte array corresponding to each image on the server.
  byte[] rawDocument = Base64.getDecoder().decode(
    firstImageBase64.getBytes());
  byte[] imageTarget = Base64.getDecoder().decode(
    secondImageBase64.getBytes());

  // Create the SelphIDVerifierOptions and configure it if needed.
  SelphIDVerifierOptions options = new SelphIDVerifierOptions();

  // Extraction
  // Check 3.1. section to initializate SelphIDVerifier.
  SelphIDFacialAuthenticationResult r = verifier.authenticateFacialWithRawDocumentImage(
    rawDocument, imageTarget, options);

  // Explore the information obtained in SelphIDFacialAuthenticationResult like similarity
  float similarity = r.getSimilarity();

  // Return if images are matching
  return r.getFacialAuthenticationStatus() == FacialAuthenticationStatus.Positive;
}

3.3.5. Facial authentication using the photograph on the document and a biometric template

The method to use is the following:

SelphIDFacialAuthenticationResult r = authenticateFacialWithRawDocumentRawTemplate(
  byte[] rawDocument,
  byte[] templateTarget,
  SelphIDVerifierOptions options
);

• The steps necessary to perform facial authentication using the document photograph and the user's biometric template are as follows (example method):

Prerequisites

• Obtain the document photograph token (base64 string) through the TokenFaceImage property using the SelphID widget.

• Obtain the biometric template (base64 string) through the TemplateRaw property using the Selphi widget.

• Send both base64 strings to the server.

boolean isMatch(String rawDocumentBase64, String templateTargetBase64) {
  // Decode base64 to get the byte array corresponding to each image on the server.
  byte[] rawDocument = Base64.getDecoder().decode(
    rawDocumentBase64.getBytes());
  byte[] templateTarget = Base64.getDecoder().decode(
    templateTargetBase64.getBytes());

  // Create the SelphIDVerifierOptions and configure it if needed.
  SelphIDVerifierOptions options = new SelphIDVerifierOptions();

  // Extraction
  // Check 3.1. section to initializate SelphIDVerifier.
  SelphIDFacialAuthenticationResult r = verifier.authenticateFacialWithRawDocumentRawTemplate(
    rawDocument, templateTarget, options);

  // Explore the information obtained in SelphIDFacialAuthenticationResult like similarity
  float similarity = r.getSimilarity();

  // Return if images are matching
  return r.getFacialAuthenticationStatus() == FacialAuthenticationStatus.Positive;
}

3.4. Document data extraction method

To obtain the document data necessary in digital Onboarding processes, the integrator has a method in the class SelphIDVerifier.

Note

The result of this method will be an object SelphIDDocumentResult that contains all the data detected in the document. For more information, see the section 3.9.3. SelphIDDocumentResult.

3.4.1. Obtaining the data detected in a document

The method to use is the following:

SelphIDDocumentResult extractDocumentWithRawDocument(
  byte[] rawDocumentBuffer,
  SelphIDVerifierOptions selphIDVerifierOptions
);

The steps necessary to obtain the data from a document are as follows (example method):

Prerequisites

• Get the value of the property TokenOCR (base64 string) using the SelphID widget.

• Send the base64 string to the server.

void printDocumentData(String tokenOCRBase64) {
  // Decode base64 to obtain the byte array corresponding to the token on the server.
  byte[] rawDocumentBuffer = Base64.getDecoder().decode(
    tokenOCRBase64.getBytes());

  // Create the SelphIDVerifierOptions and configure it if needed.
  SelphIDVerifierOptions options = new SelphIDVerifierOptions();

  // Extraction
  // Check 3.1. section to initializate SelphIDVerifier.
  SelphIDDocumentResult r = verifier.extractDocumentWithRawDocument(
    rawDocumentBuffer, options);

  // Explore the information obtained in SelphIDDocumentResult.

  // Get document keys.
  String[] keys = r.listDocumentKeys();

  // Print document data.
  for(int x=0; x<keys.length; x++) {
    System.out.println(
      keys[x] + ": " + getDocumentValue(keys[x]);
    );
  }
}

3.5. Liveness evaluation methods

To evaluate the user's liveness on the server, a necessary functionality in the digital Onboarding process to avoid fraud by photo or video, the integrator has a method for this purpose in the class SelphIDVerifier.

Note

The result of these methods will always be an object SelphIDFacialLivenessResult, explained in 3.9.4. SelphIDFacialAuthenticationResult.

3.5.1. Liveness evaluation from an image

SelphIDFacialLivenessResult r = evaluatePassiveLivenesWithImageBuffer(
  byte[] imageBuffer
);

The steps necessary to perform facial authentication using two images are as follows (example method):

Prerequisites

• Obtain a user image (base64 string) using the Selphi widget.

• Send the image base64 string to the server.

boolean isAlive(String imageBase64) {
  // Decode the base64 image to get the byte array.
  byte[] imageBuffer = Base64.getDecoder().decode(
    imageBase64.getBytes());

  // Evaluate
  // Check 3.1. section to initializate SelphIDVerifier.
  SelphIDFacialLivenessResult r = verifier.evaluatePassiveLivenesWithImageBuffer(
    imageBuffer);

  // Return if is alive
  return r.getFacialLivenessDiagnostic == FacialLivenessDiagnostic.Live;
}

3.5.2. Liveness evaluation from a tokenized image

From version 6.21.0, the tokenized image incorporates a defense mechanism against injection attacks. If an invalid token is detected, it will return NoneBecauseTokenDataError or NoneBecauseTokenSecurity as the diagnosis.

SelphIDFacialLivenessResult r = evaluatePassiveLivenessWithTokenBuffer(
  byte[] tokenBuffer
);

The steps necessary to perform facial authentication using two images are as follows (example method):

Prerequisites

• Obtain a user image (base64 string) using the Selphi widget.

• Send the image base64 string to the server.

boolean isAlive(String imageBase64) {
  // Decode the base64 image to get the byte array.
  byte[] tokenBuffer = Base64.getDecoder().decode(
    imageBase64.getBytes());

  // Evaluate
  // Check 3.1. section to initializate SelphIDVerifier.
  SelphIDFacialLivenessResult r = verifier.evaluatePassiveLivenessWithTokenBuffer(
    tokenBuffer);

  // Return if is alive
  return r.getFacialLivenessDiagnostic == FacialLivenessDiagnostic.Live;
}

3.6. 1:N identification methods

To perform 1:N searches that allow a specific biometric pattern to be identified against a database and thus obtain a set of candidates with a higher percentage of similarity, the integrator has different methods available in the class SelphIDIdentifier.

public class SelphIDIdentifier {
  // True if gallery has been created correctly.
  boolean createGallery(String galleryID) {}

  // True if gallery has been created correctly.
  boolean createGalleryWithPath(String galleryID, String galleryFilePath) {}

  // True if gallery has been removed correctly.
  boolean clearGallery(String galleryID) {}

  // Get all galleries for identification.
  String[] getAllGalleries() {}

  // True if each gallery have been removed correctly.
  boolean clearAllGalleries() {}

  // Feed a gallery with a new template using SelphIDFacialExtractionResult
  int enrollWithExtractionResult(String galleryID, String templateID, SelphIDFacialExtractionResult extractionResult) {}

  // Feed a gallery with a new template using byte[] template
  int enrollWithFacialTemplate(String galleryID, String templateID, byte[] facialTemplateBuffer) {}

  // Check if a person exists in the gallery via SelphIDFacialExtractionResult.
  SelphIDIdentifierResult identifyWithExtractionResult(String galleryID, SelphIDFacialExtractionResult extractionResult, SelphIDIdentifierOptions identifierOptions) {}

  // Check if a person exists in the gallery via byte[] template.
  SelphIDIdentifierResult identifyWithFacialTemplate(String galleryID, byte[] facialTemplateBuffer, SelphIDIdentifierOptions identifierOptions) {}

  SelphIDFacialGalleryInfo getGalleryInfo(String galleryID) {}

  boolean removeWithGalleryIndex(String galleryID, int templateIndex) {}

  boolean removeWithTemplateID(String galleryID, String templateID) {}
}

3.6.1. Construction of the search gallery

As a prerequisite for performing identification operations, a gallery must be created and the set of biometric patterns on which the search will be carried out must be registered in it. To add templates to the gallery, you can use the following methods:

public class SelphIDIdentifier {
  int enrollWithExtractionResult(
    String galleryID,
    String templateID,
    SelphIDFacialExtractionResult extractionResult
  ) {}

  int enrollWithFacialTemplate(
    String galleryID,
    String templateID,
    byte[] facialTemplateBuffer
  ) {}
}

In both methods, the identifier of the gallery to which the template should be added will be specified, as well as a logical identifier referring to the application's business logic, so that the candidates obtained as a result of a search in the gallery can be linked to it.

// 1. Create the gallery.
String galleryID = "my-new-id-or-uuid-1";
createGallery(galleryID);

// 2. Generate the facial templates from the images if you do not have them.
byte[] image1 = ...;
byte[] image2 = ...;
SelphIDVerifierOptions options = new SelphIDVerifierOptions();

SelphIDFacialExtractionResult extractionResult1 = extractFacialWithImageBuffer(
  image1, options);

SelphIDFacialExtractionResult extractionResult2 = extractFacialWithImageBuffer(
  image2, options);

// 3. The obtained facial templates will be added to the gallery by using any of the following methods of the `SelphIDIdentifier` class (you need to initializate it).

//    3.1. Create / Generate the template ID that will have in gallery
String templateID1 = "my-new-id-or-uuid-2";
String templateID2 = "my-new-id-or-uuid-3";

//    3.2. Insert the templates into the gallery with enrollWithExtractionResult
identifier.enrollWithExtractionResult(galleryID, templateID1, extractionResult1);

//    3.3. Insert the templates into the gallery with enrollWithFacialTemplate
byte[] facialTemplateBuffer = extractionResult2.getFacialTemplate();

identifier.enrollWithFacialTemplate(galleryID, templateID2, facialTemplateBuffer);

Note

To register a biometric template in a gallery, it will be necessary to generate the equivalent facial pattern or FacialTemplate by means of any of the following methods of the class SelphIDVerifier:

• ExtractFacialWithRawTemplate

• ExtractFacialWithImageBuffer

See the section 3.2.1. Facial extraction using an image.

3.6.2. Identification of a template against a search gallery

The search process will be carried out using either of the following two methods of the class SelphIDIdentifier:

public class SelphIDIdentifier {
  SelphIDIdentifierResult identifyWithExtractionResult(
    String galleryID,
    SelphIDFacialExtractionResult extractionResult,
    SelphIDIdentifierOptions identifierOptions
  ) {}

  SelphIDIdentifierResult identifyWithFacialTemplate(
    String galleryID,
    byte[] facialTemplateBuffer,
    SelphIDIdentifierOptions identifierOptions
  ) {}
}

The gallery identifier and an object will be specified SelphIDIdentifierOptions with the following search options:

• MaxIdentificationCandidates, to indicate the maximum number of returned candidates, sorted from highest to lowest similarity percentage.

• MinIdentificationSimilarity, to indicate the minimum similarity threshold in the comparison for a candidate to be included in the result set.

Note

By default, MaxIdentificationCandidates it will be 20 and MinIdentificationSimilarity it will be 0f.

Next, we will see an example with both methods:

// 1. For an existing gallery we only need its ID and the image to search for that person in the gallery.
String galleryID = "galleryID";
byte[] imageToSearch = ...;
SelphIDIdentifierOptions identifierOptions = new SelphIDIdentifierOptions();

// 2. Configure the SelphIDIdentifierOptions
identifierOptions.setMaxIdentificationCandidates(5);
identifierOptions.setMinIdentificationSimilarity(0.6f);

// 3. Extract the facial template
SelphIDVerifierOptions verifierOptions = new SelphIDVerifierOptions();

SelphIDFacialExtractionResult extractionResult = identifier.extractFacialWithImageBuffer(
  imageToSearch, verifierOptions);

// 4. Search it with the identifyWithExtractionResult or identifyWithFacialTemplate if you alredy have the facial template.
SelphIDIdentifierResult result = identifier.identifyWithExtractionResult(
  galleryID, extractionResult, identifierOptions);

byte[] facialTemplateBuffer = extractionResult.getFacialTemplate();
SelphIDIdentifierResult result = identifyWithFacialTemplate(
  galleryID, facialTemplateBuffer, identifierOptions);

// 5. View the results. We obtain an array with all possible coincidence, so if for example we want to get the first coincidence:
if (result.size() > 0) {
  FacialAuthenticationStatus authenticate = identifierResult.getFacialAuthenticationStatus(0);
  float similarity = result.getSimilarity(0);
  String templateId = result.getTemplateID(0);
}

Note

To learn more about SelphIDIdentifierResult, see the section 3.9.5. SelphIDIdentifierResult.

3.6.3. Remove a template from the gallery

The deletion process consists of blocking a biometric template from a specific gallery so that it is not taken into account in identification processes. If we use the environment variable FACEPHI_SELPHID_GALLERY_REMOVE_METHOD=noerase, this deletion does not reduce the size of the gallery or the indexing of the associated biometric templates. Conversely, omitting this variable or using FACEPHI_SELPHID_GALLERY_REMOVE_METHOD=erase will reduce the gallery size after deletion, altering the indexing of the templates.

public class SelphIDIdentifier {
  boolean removeWithGalleryIndex(
    String galleryID,
    int templateIndex
  ) {}

  boolean removeWithTemplateID(
    String galleryID,
    String templateID
  ) {}

}

The deletion process is carried out with the following method of the class SelphIDIdentifier:

// For a example we are going to remove an specific user.
String galleryID = "galleryID";
byte[] facialTemplateBuffer = ...;
SelphIDIdentifierOptions identifierOptions = new SelphIDIdentifierOptions();
identifierOptions.setMaxIdentificationCandidates(1);
identifierOptions.setMinIdentificationSimilarity(0.5f);

// Search the coincidence template in gallery.
SelphIDIdentifierResult identifierResult = identifier.identifyWithFacialTemplate(
  galleryID, facialTemplateBuffer, identifierOptions);

// If coincidence have been found and it is matching, it will be removed.
if (result.size() > 0 &&
  identifierResult.getFacialAuthenticationStatus(0) == FacialAuthenticationStatus.Positive) {
  // Get the index of the template
  int templateIndex = identifierResult.getGalleryIndex(0);

  boolean removed = removeWithGalleryIndex(galleryID, templateIndex);

  if (removed) {
    System.out.println("Template correctly removed.");
  }
}

3.6.4. Query and remove obsolete templates

From version 6.17.0, each biometric pattern stores the timestamp (system clock) at which it was indexed in the gallery. This allows querying and deleting "expired" templates according to specific criteria.

public class SelphIDIdentifier {
  String[] listObsoleteGalleryTemplateIDs(
    String galleryID,
    int intervalSeconds
  ) {}

  String[] removeObsoleteGalleryTemplateIDs(
    String galleryID,
    int intervalSeconds
  ) {}
}

In both cases, the template IDs whose timestamps are earlier than the specified interval (in seconds) will be listed. In the case of removeObsoleteGalleryTemplateIDs(), the operation will be atomic and will remove all obsolete patterns in a single operation. If FACEPHI_SELPHID_GALLERY_REMOVE_METHOD=erase, the gallery size will be reduced and the remaining patterns will be reindexed.

// For a example we are going to remove an specific user.
String galleryID = "galleryID";

// Remove all biometric patterns older than a day
String [] obsoleteIDs = removeObsoleteGalleryTemplateIDs(galleryID, 24 * 3600);

if (obsoleteIDs.length > 0) {
  System.out.println("Biometric patterns removed from gallery.");
  for (int i = 0; i < obsoleteIDs.length; ++i)
    System.out.println(obsoleteIDs[i]);
}

3.6.5. Query gallery information

The purpose of querying a gallery is to serve as a preliminary step before being able to perform other queries on it.

The process will be carried out with the following class of SelphIDIdentifier:

public class SelphIDIdentifier {
  SelphIDFacialGalleryInfo getGalleryInfo(
    String galleryID
  ) {}
}

A gallery identifier must be used to query the specific gallery. Next, we will see what the object SelphIDFacialGalleryInfo:

public class SelphIDFacialGalleryInfo {
  // Gets if gallery is valid.
  boolean getValidGallery();

  // Gets gallery ID.
  String getGalleryID();

  // Gets gallery size.
  int getGallerySize();

  // Obtain a template with the index.
  String getTemplateID(int index);

  // Obtain all indices from a gallery that matches a exact value.
  int[] getIndicesWithTemplateID(String templateID);
}

3.6.6. Query the indices that match a templateID specific

The process of querying all the indices in a gallery that match an exact value of templateID must be carried out with the following method of SelphIDFacialGalleryInfo that we have seen in the previous section:

Important

Starting with SelphID 6.15.0, items with duplicate templateID are not allowed.

public class SelphIDFacialGalleryInfo {
  int[] getIndicesWithTemplateID(
    String templateID
  );
}

A templateID that matches the templateID being searched for in the gallery.

To do this, it is necessary to have an instance of SelphIDFacialGalleryInfo with valid data:

String galleryID = "galleryID";
String templateID = "templateID";

SelphIDFacialGalleryInfo galleryInfo = identifier.getGalleryInfo(galleryID);

int[] indicesTemplateID = galleryInfo.getIndicesWithTemplateID(templateID);

3.7. Orchestrator

The orchestrator allows facial authentication and the person's liveness check to be obtained in the same call. We can choose to perform the check with an image and a template, or with two templates.

Important

The liveness check will only be performed after a successful authentication.

SelphIDVerifierResult r = verifySelphIDWithImageRawTemplate(
  byte[] imageBuffer,
  byte[] templateTarget,
  SelphIDVerifierOptions options
);

SelphIDVerifierResult r = verifySelphIDWithRawTemplates(
  byte[] templateQuery,
  byte[] templateTarget,
  SelphIDVerifierOptions options
);

Note

For more information about SelphIDVerifierResult, see the section 3.9.6. SelphIDVerifierResult.

3.8. API Tracking

From version 4.1.0, SelphID-SDK incorporates event tracking functionality that allows monitoring and visualizing API activity through a web interface. The SelphID license will include all the necessary data to access the platform (in the single-tenant version).

All the previous methods from other API versions are still valid. Some duplicate methods have been added that now receive a new parameter containing tokenized data with the essential information to communicate with the tracking server. This parameter is called extraData.

3.8.1. Multi-tenant Version

From version 4.3.0, SelphID-SDK allows two operating modes with respect to event logging through API Tracking:

• Single-tenant: The API Tracking service connection data are encrypted inside the SelphID-SDK license and will be used in all service calls.

• Multi-tenant: The connection data will be received in each call through the mobile application. This will allow the SDK to log events on different servers depending on the client making the call.

Important

To enable multi-tenant mode, the tracking data must not be included in the SelphID-SDK license. Otherwise, single-tenant mode will be activated when the backend starts.

From version 5.0.0, it is possible to switch between Single-tenant and Multi-tenant modes at runtime, using these methods of SelphIDVerifier:

void setMultitenantMode(boolean multiTenant);

boolean isMultitenantEnabled();

3.8.2. Logging

The following method allows decrypted tokenized data in rawDocumentBuffer, such as OCR, document images, etc. The parameter extraData must be sent the data required for the tracking service.

SelphIDDocumentResult r = extractDocumentWithRawDocument(
  byte[] rawDocumentBuffer,
  byte[] extraData,
  SelphIDVerifierOptions options
);

The following methods receive an encrypted image rawTemplateBufferTarget or an unencrypted image imageBufferTarget, to compare it with the image extracted from the document rawDocumentBufferQuery. In both cases, the data required for the tracking service must be sent in the parameter extraData.

SelphIDFacialAuthenticationResult r = authenticateFacialWithRawDocumentRawTemplate(
  byte[] rawDocumentBufferQuery,
  byte[] rawTemplateBufferTarget,
  byte[] extraData,
  SelphIDVerifierOptions options
);

SelphIDFacialAuthenticationResult r = authenticateFacialWithRawDocumentImage(
  byte[] rawDocumentBufferQuery,
  byte[] imageBufferTarget,
  byte[] extraData,
  SelphIDVerifierOptions options
);

3.8.3. SelphIDVerifierOptions

The following methods, added to the class SelphIDVerifierOptions, allow the information entered by the client to be represented on the tracking servers, in the logging use case.

public class SelphIDVerifierOptions {
  void setElapsedTimeAllowed(int elapsedTimeAllowed);
  void setFutureTimeAllowed(int futureTimeAllowed);
  void setFacialDetectionType(FacialDetectionType facialDetectionType);
  void setMinFaceAbs(int minFaceAbs);
  void setMinFaceRel(float minFaceRel);
  void setFalseDetectRate(float rate);
  void setMinIODThreshold(int minIODThreshold);
  void setMaxPoseThreshold(int maxPoseThreshold);
  void setMinimumFacialQuality(int minimumFacialQuality);
  void setAnalyticsDetection(boolean analyticsDetection);
  void setFacialTemplateRawExtraction(boolean facialTemplateRawExtraction);
  void setOptionalDataClientInformation(String json);
  void setCustomFacialAuthenticationThreshold(int customFacialAuthenticationThreshold);
  void setLivenessDepth(LivenessDepth livenessDepth);
}

The input parameter of the method setOptionalDataClientInformation must be a well-formed JSON that will accept the following keys:

{
  "address": "String",
  "birthDate": "String",
  "birthPlace": "String",
  "city": "String",
  "documentNumber": "String",
  "name": "String",
  "nationality": "String",
  "surname": "String"
}

Note

Any other key will be ignored. More keys will be supported in the future.

From version 6.17.0, the property was added futureTimeAllowed. This allows setting a time interval (in seconds) during which tokenized templates and images with a future date will be accepted, returning true in the method getValidTimeStamp(). This aims to mitigate time zone differences between devices. This value can be configured globally through the environment variable FACEPHI_SELPHID_FUTURE_TIME_ALLOWED=3600.

From version 6.18.0, we can specify which Liveness pipelines we want to run for each operation through setLivenessDepth(). In the case of None (default value), the global configuration established by FACEPHI_SELPHID_FACIALLIVENESS_DEPTH.

3.8.4. Authentication

The following methods are available to perform authentication. The parameters rawTemplateBuffer receive the encrypted image, and the parameter imagebufferQuery receives the unencrypted image. In both cases, the data required for the tracking service must be sent in the parameter extraData.

SelphIDFacialAuthenticationResult r = authenticateFacialWithRawTemplates(
  byte[] rawTemplateBufferQuery,
  byte[] rawTemplateBufferTarget,
  byte[] extraData,
  SelphIDVerifierOptions options
);

SelphIDFacialAuthenticationResult r = authenticateFacialWithImageRawTemplate(
  byte[] imageBufferQuery,
  byte[] rawTemplateBufferTarget,
  byte[] extraData,
  SelphIDVerifierOptions options
);

3.8.5. Passive liveness

The following methods are available to perform the passive liveness check. The parameter tokenBuffer receives the encrypted image and imageBuffer the unencrypted image. In both cases, the data required for the tracking service must be sent in the parameter extraData.

SelphIDFacialLivenessResult r = evaluatePassiveLivenessWithTokenBuffer(
  byte[] tokenBuffer,
  byte[] extraData
);

SelphIDFacialLivenessResult r = evaluatePassiveLivenesWithImageBuffer(
  byte[] imageBuffer,
  byte[] extraData
);

3.8.6. Custom events

From version 4.5.0, SelphID implements the ability to send custom events to the Tracking API, not linked to any internal SDK operation. All custom event operations return a status code and a message, within an object SelphIDApiTrackingResult.

The following method allows sending the following event to the Tracking API: Facial authentication, using the parameters authStatus and similarity. We can also log the image(s) involved in the authentication in the API Tracking service. Both images are optional, accepting null or empty buffers.

SelphIDApiTrackingResult r = authenticateFacialTrackingEvent(
  TrackingFamily family,
  FacialAuthenticationStatus authStatus,
  float similarity,
  String source,
  byte[] imageBufferQuery,
  byte[] imageBufferTarget,
  byte[] extraData
);

Possible values of TrackingFamily:

public enum TrackingFamily {
  OnBoarding,
  Authentication
}

The following method allows sending the following event to the Tracking API: Liveness, using the parameters diagnostic and similarity. We can also log the image involved in the liveness process in the API Tracking service, although it is optional, accepting a null or empty buffer.

SelphIDApiTrackingResult r = evaluatePassiveLivenessTrackingEvent(
  TrackingFamily family,
  FacialLivenessDiagnostic diagnostic,
  String source,
  byte[] imageBuffer,
  byte[] extraData
);

The following method allows sending the following event to the Tracking API: Voice authentication, using the parameter probability. We can also log the audio traces involved in the voice authentication process in the API Tracking service. Both buffers are optional, accepting null or empty values.

SelphIDApiTrackingResult r = voiceAuthenticationTrackingEvent(
  float probabiliy,
  String source,
  byte[] audioDataBufferQuery,
  byte[] audioDataBufferTarget,
  byte[] extraData
);

The following method allows sending a custom OCR event to the API Tracking server.

SelphIDApiTrackingResult r =  ocrTrackingEvent(
  String ocrDataJson,
  String source,
  byte[] extraData
);

ocrDataJson is a key-value dictionary in well-formed JSON format. It accepts any kind of key name with any string value:

{
  "OCR_Key1": "OCR_Value1",
  "OCR_Key2": "OCR_Value2",
  "OCR_Key3": "OCR_Value3",
  "OCR_Key4": "OCR_Value4",
  "OCR_Key5": "OCR_Value5"
}

The following method allows sending a custom SECURITY_INFO_DATA event to the API Tracking server:

  SelphIDApiTrackingResult r = securityInfoTrackingEvent(
  String securityDataJson,
  boolean succeed,
  String source,
  byte[] extraData
  );

securityDataJson are the security data in JSON format:

{
  "Security_Key1": "Security_Value1",
  "Security_Key2": "Security_Value2",
  "Security_Key3": "Security_Value3",
  "Security_Key4": "Security_Value4",
  "Security_Key5": "Security_Value5"
}

succeed is a boolean value indicating whether the retrieval of the security data was successful or not, and source is the name of the service or the source of the security data.

For all custom event operations, we can modify the encrypted field eventSource within the token extraData.

byte[] extraData2 = setTrackingEventSource(
  String eventSource,
  byte[] extraData
);

Within custom events, there is the possibility of closing the operation using the following method:

SelphIDApiTrackingResult r = finishTrackingEvent(
  TrackingFamily family,
  OperationResultStatus status,
  OperationResultReason reason,
  byte[] extraData
);

This method will log the events of Operation result (Operation result) and Step change finish (Step change finish), which close the operation.

Important

The meaning of these attributes, including those enums, will be determined by the user.

Possible values of OperationResultStatus:

public enum OperationResultStatus {
  Succeeded,

  // Denied.
  Denied,

  // Error.
  Error,

  // Cancelled.
  Cancelled
}

Possible values of OperationResultReason:

public enum OperationResultReason {
  // We do not specify a concrete reason.
  None,

  // Some error using the SDK.
  InternalError,

  // The operation was canceled by the user.
  CancelledByUser,

  // The set timeout has expired.
  Timeout,

  // Document validation failed.
  DocumentValidationNotPassed,

  // Error during document validation.
  DocumentValidationError,

  // Authentication failed.
  AuthenticationNotPassed,

  // Error during authentication.
  AuthenticationError,

  // Liveness failed.
  LivenessNotPassed,

  // Error during liveness.
  LivenessError
}

3.8.7. Proxy server

Since version 4.5.5 of SelphID-SDK, it is possible to send requests to the Tracking API through a proxy server. To configure the proxy parameters, use the following method:

setTrackingProxy(
        String proxyHost,
        int proxyPort,
        String proxyUser,
        String proxyPass);

To disable the proxy, an empty string must be passed as the parameter proxyHost.

3.9. Description of API results

The following properties, in the result classes, allow you to evaluate the results of each of the methods mentioned above.

From version 6.18.0, in addition to verifying the validity of a token through getValidTimeStamp(), we can now obtain the timestamp embedded in the token itself through getTokenTimeStamp(). This affects:

• SelphIDFacialExtractionResult.

• SelphIDFacialAuthenticationResult.

• SelphIDDocumentResult.

• SelphIDFacialLivenessResult.

3.9.1. SelphIDFacialExtractionResult

It presents different properties for evaluating the result of facial extraction:

public class SelphIDFacialExtractionResult {
  // Indicates whether the extraction was able to process successfully.
  boolean getExtractionOK() {}

  // Biometric pattern of the detected person.
  byte[] getFacialTemplate() {}

  // Value (0, 1) that indicates the degree of reliability of the extraction.
  float getFaceConfidence() {}

  // Location of landmark points detected in the image.
  Point getLeftEye() {}
  Point getRightEye() {}
  Point getChin() {}
  Point getNose() {}
  Point getLeftMouth() {}
  Point getRigthMouth() {}

  // Interocular distance.
  int getIOD() {}

  // Orientation of the face with respect to the camera. Possible values are as follows:
  FacialPose getFacialPose() {}

  // Face Orientation Angles.
  float getYaw() {}
  float getPitch() {}
  float getRoll() {}

  // Value (0, 1) that indicates the quality of the input image.
  float getImageQuality() {}

  // Indicates the quality of the detected face. Possible values are as follows:
  FacialQuality getFacialQuality() {}

  // Indicates if the person wears glasses. Possible values are as follows:
  FacialGlasses getGlasses() {}

  // Numerical value indicating the approximate age of the person.
  int getAge() {}

  // Gender of the person. Possible values are as follows:
  FacialGender getGender() {}

  // Value (0, 1) that indicating the probability that the person wears a mask.
  float getFacialMask() {}

  // Gets if the time stamp is valid.
  boolean getValidTimeStamp() {}

  // Gets the token time stamp.
  long getTokenTimeStamp() {}
}

Possible values of FacialPose:

public enum FacialPose {
  // Unknown or not computed.
  None,

  // Looking straight ahead.
  Frontal,

  // Person looking to the right.
  RightAngled,

  // Person looking to the left.
  LeftAngled
}

Possible values of FacialQuality:

public enum FacialQuality {
  None,
  Bad,
  Regular,
  Good
}

Possible values of Glasses:

public enum Glasses {
  None,
  Eyes,
  Sun
}

Possible values of Gender:

public enum Gender {
  None,
  Male,
  Female
}

3.9.2. SelphIDFacialAuthenticationResult

It presents different properties for evaluating the result of biometric authentication:

public class SelphIDFacialAuthenticationResult {
  // Results of a facial authentication process.
  FacialAuthenticationStatus getFacialAuthenticationStatus() {}

  // Similarity value between 0 and 1 representing the similarity between the faces of the two images.
  float getSimilarity() {}

  // Gets if the time stamp is valid.
  boolean getValidTimeStamp() {}

  // Gets the token time stamp.
  long getTokenTimeStamp() {}
}

Important

To evaluate the result you must use the property FacialAuthenticationStatus; the value similarity is only used for statistical purposes.

Possible values of FacialAuthenticationStatus:

public enum FacialAuthenticationStatus {
  // Biometric authentication could not be performed.
  None,

  // Negative Authentication result.
  Negative,

  // DEPRECATED.
  Uncertain,

  // Positive Authentication result.
  Positive,

  // Biometric authentication could not be performed because the maximum allowed angle between faces of each image provided was exceeded.
  NoneBecausePoseExceeded,

  // Biometric authentication could not be performed because biometric feature extraction could not be performed on any of the images provided.
  NoneBecauseInvalidExtractions
}

3.9.3. SelphIDDocumentResult

It presents different methods for retrieving the images used in the process and the data read from the document. The methods are as follows:

public class SelphIDDocumentResult {
  // Obtains all the keys associated with each of the read data from the document.
  String[] listDocumentKeys() {}

  // Obtains a certain data read from the document by means of its associated key.
  String getDocumentValue(String key) {}

  // Obtains all the keys associated with each of the read images from the document.
  String[] listImageKeys() {}

  // Obtains a certain image of the document by means of its associated key.
  byte[] getImage(String key) {}

  // Gets the ExtraData key list.
  String[] listExtraDataKeys() {}

  // Gets the ExtraData value for the key provided.
  String getExtraDataValue(String key) {}

  // Gets if the time stamp is valid.
  boolean getValidTimeStamp() {}

  // Gets the token time stamp.
  long getTokenTimeStamp() {}
}

3.9.4. SelphIDFacialLivenessResult

Presents the property FacialLivenessDiagnostic to evaluate the result of the passive liveness check diagnostic.

public class SelphIDFacialLivenessResult {
  // Gets facial liveness diagnostic.
  FacialLivenessDiagnostic getFacialLivenessDiagnostic() {}

  // Added in 6.18.0
  // Gets additional information when facial liveness diagnostic is NoLive.
  SelphIDNoLiveDetails getNoLiveDetails() {}

  // Gets the valid timestamp
  boolean getValidTimeStamp() {}

  // Gets the token time stamp.
  long getTokenTimeStamp() {}
}

Possible values of FacialLivenessDiagnostic:

public enum FacialLivenessDiagnostic {
  // Liveness Diagnostic could not be evaluated.
  None,

  // A fraud condition has been detected, a video or a photograph.
  // DEPRECATED > use "NoLive".
  Spoof,

  // DEPRECATED.
  Uncertain,

  // The subject passes the liveness diagnostic.
  Live,

  // Liveness could not be evaluated because of the low quality of the images used.
  NoneBecauseBadQuality,

  // Liveness could not be evaluated as the face is too close to the camera.
  NoneBecauseFaceTooClose,

  // Liveness could not be evaluated as no faces were detected in the images used.
  NoneBecauseFaceNotFound,

  // Liveness could not be evaluated as very small faces were detected in the images used.
  NoneBecauseFaceTooSmall,

  // Liveness could not be evaluated because the angle between faces was exceeded.
  NoneBecauseAngleTooLarge,

  // Liveness could not be evaluated because of the format of the images used.
  NoneBecauseImageDataError,

  // Liveness could not be evaluated due to an internal error.
  NoneBecauseInternalError,

  // Liveness could not be evaluated due to an error in the processing of the images used.
  NoneBecauseImagePreprocessError,

  // Liveness could not be evaluated because there are too many people at the scene.
  NoneBecauseTooManyFaces,

  // Liveness could not be evaluated as the face is too close to the image borders.
  NoneBecauseFaceTooCloseToBorder,

  // Liveness could not be evaluated as the image used is cropped.
  NoneBecauseFaceCropped,

  // The liveness check could not be evaluated due to a licensing error.
  NoneBecauseLicenseError,

  // Liveness could not be evaluated because the person's face is occluded.
  NoneBecauseFaceOccluded,

  // The image does not correspond to a real person.
  NoLive,

  // Liveness could not be evaluated because the person's eyes are closed.
  NoneBecauseEyesClosed,

  // Liveness could not be evaluated because the person's eyes are occluded.
  NoneBecauseEyesOccluded,

  // None due to token data error or malformed.
  NoneBecauseTokenDataError,

  // None due to the token's internal security measures having been broken.
  NoneBecauseTokenSecurity
}

Starting with version 6.18.0, the structure SelphIDNoLiveDetails is included with additional information about the case NoLive. In the case Live, we can also consult the pipeline scores.

// SelphID details for FacialLivenessDiagnostic::NoLive case.
public class SelphIDNoLiveDetails {
  // High-level main cause of the NoLive diagnostic.
  NoLiveMainCause getNoLiveMainCause() {}

  // Status of the facial Presentation Attack Detection (fPAD).
  FPadStatus getFPadStatus() {}

  // Normalized fPAD score (0..1), if available.
  float getFPadScore() {}

  // Status of the facial Manipulation Attack Detection (fMAD).
  FMadStatus getFMadStatus() {}

  // Normalized fMAD score (0..1), if available.
  float getFMadScore() {}

  // Normalized coercion score (0..1), if available.
  float getCoercionScore() {}

  // Human-readable reason message, for logs/Backoffice.
  String getReasonMessage() {}
}

3.9.5. SelphIDIdentifierResult

It presents different methods for obtaining the comparison information for each of the candidates returned as a result of a 1:N search. They are as follows:

public class SelphIDIdentifierResult {
  // Gets the number of candidates obtained in the search.
  int size() {}

  // Gets similarity from result index.
  float getSimilarity(int index) {}

  // Gets gallery index from result index.
  int getGalleryIndex(int index) {}

  // Gets templateID from result index.
  String getTemplateID(int index) {}

  // Gets the status code from the comparison made between the search template and the indicated candidate.
  FacialAuthenticationStatus getFacialAuthenticationStatus(int index) {}

  // Obtains additional information in case the biometric comparison between the search template and the indicated candidate was positive.
  FacialAuthenticationDetail getFacialAuthenticationDetail(int index) {}
}

Possible values of FacialAuthenticationStatus:

public enum FacialAuthenticationStatus {
  // The biometric comparison could not be performed.
  None,

  // The facial patterns do not match.
  Negative,

  // DEPRECATED.
  Uncertain,

  // Facial patterns do match.
  Positive,

  // The biometric comparison could not be performed because the face in some of the captures is located at a too high rotation angle with respect to the camera.
  NoneBecausePoseExceed,

  // The biometric comparison could not be performed because no face could be detected in any of the captures made.
  NoneBecauseInvalidExtractions
}

Possible values of FacialAuthenticationDetail:

public enum FacialAuthenticationDetail {
  // The comparison was not successful.
  None,

  // The facial patterns do match with a low percentage of similarity.
  PositiveLowSecurityLevel,

  // The facial patterns do match with an average percentage of similarity.
  PositiveMediumSecurityLevel,

  // Facial patterns do match with a high percentage of similarity.,
  PositiveHighSecurityLevel
}

3.9.6. SelphIDVerifierResult

It presents different methods for obtaining information from the orchestrator. They are as follows:

public class SelphIDVerifierResult {
  // Obtains information about the document.
  SelphIDDocumentResult getSelphIDDocumentResult() {}

  // Obtains information about the authentication process.
  SelphIDFacialAuthenticationResult GetSelphIDFacialAuthenticationResult() {}

  // Obtains information about the liveness process.
  SelphIDFacialLivenessResult GetSelphIDFacialLivenessResult() {}
}

Note

For more information:

• 3.9.2. SelphIDFacialAuthenticationResult

• 3.9.3. SelphIDDocumentResult

• 3.9.4. SelphIDFacialLivenessResult

3.9.7. SelphIDApiTrackingResult

It presents different methods for obtaining information on the API Tracking operation. They are as follows:

public class SelphIDApiTrackingResult {
  // Obtains the Tracking request HTTP result.
  int GetTrackingStatus() {}

  // Obtains the Tracking request message.
  String GetTrackingMessage() {}
}

3.10. Description of SelphIDException

If an error occurs within SelphID-SDK, the SelphIDException exception will be thrown.

public class SelphIDException extends Exception {
  // Get the type of exception that occurred.
  SelphIDExceptionType getExceptionType() {}
}

Possible values of SelphIDExceptionType:

public enum SelphIDExceptionType {
  // Error in license content.
  ErrorLicenseContent,

  // The license has expired.
  ErrorLicenseExpired,

  // Error in license HostID.
  ErrorLicenseHostID,

  // Error in facial template.
  ErrorFacialTemplate,

  // Error loading library.
  // DEPRECATED.
  ErrorLoadingLibrary,

  // Error in license usage logging.
  ErrorLicenseUsageLogging,

  // Facial image with error or invalid.
  ErrorFacialImage,

  // Error in document data.
  ErrorDocumentData,

  // Error in network license.
  ErrorLicenseNetwork,

  // Error because network license connections have been exceeded.
  ErrorLicenseNetworkConnectionsExceeded,

  // Gallery size reached.
  ErrorLicenseGallerySizeReached,

  // Invalid options.
  ErrorInvalidOptions,

  // The license is too old.
  ErrorLicenseTooOld,

  // Error because a feature is unavailable.
  ErrorUnavailableFeature,

  // Error because of an incompatible facial template.
  ErrorIncompatibleFacialTemplate,

  // Error when accessing the configuration file.
  ErrorConfigurationFileAccess,

  // Error when accessing Tracking API data.
  ErrorTrackingFileAccess,

  // Error when loading the Tracking API configuration file.
  // DEPRECATED.
  ErrorLoadingTrackingFile,

  // SelphID configuration variables are empty (config file or environment variables).
  ErrorConfigVarsEmpty,

  // `FACEPHI_SELPHID_INSTALL_PATH` key is empty.
  ErrorInstallPathEmpty,

  // `FACEPHI_SELPHID_FACIALLIVENESS_PATH_KEY` key is empty.
  ErrorLivenessDataPathEmpty,

  // Error when loading the facial authentication library.
  ErrorLoadingFacialLibrary,

  // Error when loading the liveness library.
  ErrorLoadingLivenessLibrary,

  // Internal error when execute the facial extraction.
  ErrorProcessingFacial,

  // Internal error when execute the liveness check.
  ErrorProcessingLiveness,

  // Error when accessing a gallery in disk.
  ErrorGalleryFile
}