> For the complete documentation index, see [llms.txt](https://docs.facephi.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.facephi.com/docs.facephi-en/sdks/backend-sdk/selphid/technical_documentation/api_reference.md).

# 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`

```java
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

```java
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.

```java
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](#310-descripción-de-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](#391-selphidfacialextractionresult).

#### 3.2.1. Facial extraction using an image

The method to use is the following:

```java
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.

```java
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:

```java
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.

```java
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](#392-selphidfacialauthenticationresult).

#### 3.3.1. Facial authentication using images

```java
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.

```java
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:

```java
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.

```java
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:

```java
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.

```java
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:

```java
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.

```java
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:

```java
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.

```java
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](#393-selphiddocumentresult).

#### 3.4.1. Obtaining the data detected in a document

The method to use is the following:

```java
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.

```java
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](#394-selphidfaciallivenessresult).

#### 3.5.1. Liveness evaluation from an image

```java
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.

```java
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.

```java
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.

```java
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`.

```java
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:

```java
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.

```java
// 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](#321-extracción-facial-mediante-una-imagen).

#### 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`:

```java
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:

```java
// 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](#395-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.

```java
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`:

```java
// 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.

```java
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.

```java
// 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`:

```java
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`:

```java
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](#365-consultar-información-de-una-galería):

> **Important**
>
> Starting with SelphID `6.15.0`, **items with duplicate templateID are not allowed**.

```java
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:

```java
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.

```java
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](#396-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`:

```java
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.

```java
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`.

```java
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.

```java
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:

```json
{
  "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`.

```java
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`.

```java
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.

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

Possible values of `TrackingFamily`:

```java
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.

```java
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.

```java
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.

```java
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:

```json
{
  "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:

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

`securityDataJson` are the security data in JSON format:

```json
{
  "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`.

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

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

```java
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`:

```java
public enum OperationResultStatus {
  Succeeded,

  // Denied.
  Denied,

  // Error.
  Error,

  // Cancelled.
  Cancelled
}
```

Possible values of `OperationResultReason`:

```java
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:

```java
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:

```java
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`:

```java
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`:

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

Possible values of `Glasses`:

```java
public enum Glasses {
  None,
  Eyes,
  Sun
}
```

Possible values of `Gender`:

```java
public enum Gender {
  None,
  Male,
  Female
}
```

### 3.9.2. SelphIDFacialAuthenticationResult

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

```java
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`:

```java
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:

```java
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.

```java
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`:

```java
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.

```java
// 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:

```java
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`:

```java
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`:

```java
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:

```java
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](#392-selphidfacialauthenticationresult)
> * [3.9.3. SelphIDDocumentResult](#393-selphiddocumentresult)
> * [3.9.4. SelphIDFacialLivenessResult](#394-selphidfaciallivenessresult)

### 3.9.7. SelphIDApiTrackingResult

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

```java
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.

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

Possible values of `SelphIDExceptionType`:

```java
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
}
```