> 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/rest-api/identity-api/identity-api-reference/onboarding/civil-validation/ecuador.md).

# Ecuador

Civil validation service for Ecuador. Performs Identity Verification against the data in Ecuador's Civil Registry.

{% hint style="info" %}
For Ecuador, the parameter `documentCode` (fingerprintCode) is required in all operations.
{% endhint %}

### Endpoint

```
POST /services/civilValidation
```

### Headers

| Name          | Type   | Required | Description                                                |
| ------------- | ------ | -------- | ---------------------------------------------------------- |
| **x-api-key** | string | **Yes**  | Access authorization API key.                              |
| **family**    | string | No       | Value: **Onboarding**. Required with the tracking service. |

{% hint style="info" %}
All calls to the Endpoints for Tracking with **Identity Platform** must contain the header `family`.
{% endhint %}

## Full Validation Mobile

Performs data validation and facial matching against Ecuador's Civil Registry using the mobile platform.

### Request body

**Content-Type:** `application/json`

#### Parameters

| Parameter              | Type    | Required | Description                                                                                                                                                                     |
| ---------------------- | ------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `operation`            | string  | **Yes**  | Validation operation to perform. Value: `"FULL"`.                                                                                                                               |
| `platform`             | string  | **Yes**  | Platform from which the request is made. Value: `"MOBILE"`.                                                                                                                     |
| `tokenOcr`             | string  | **Yes**  | Token generated by the native or hybrid SelphID Widget, encrypted in AES256 and Tokenized, sent in Base64 format. It contains the OCR result of the captured Identity document. |
| `templateRaw`          | string  | **Yes**  | Biometric Template generated by the Selphi Widget. Required for FACIAL or FULL operations.                                                                                      |
| `documentCode`         | string  | **Yes**  | Document code (fingerprintCode), required for validation in Ecuador.                                                                                                            |
| `documentNumber`       | string  | No       | User's document number.                                                                                                                                                         |
| `countryCode`          | string  | **Yes**  | Country code in ISO 3166-1 alpha-3 format. Value: `"ECU"`.                                                                                                                      |
| `returnPII`            | boolean | No       | Indicates whether the personal data generated by the OCR service and the response from the Civil Registry should be returned.                                                   |
| `documentValidation`   | boolean | No       | Indicates whether document validation should be started, returning `scanReference` and `type`.                                                                                  |
| `tracking`             | object  | No       | Object that represents the necessary tracking information.                                                                                                                      |
| `tracking.extraData`   | string  | No       | Token generated by the Mobile/Web SDK. Contains tokenized tracking information with the Platform.                                                                               |
| `tracking.operationId` | string  | No       | Operation identifier generated by the Mobile/Web SDK.                                                                                                                           |

#### Request example

```json
{
  "operation": "FULL",
  "platform": "MOBILE",
  "tokenOcr": "base64TokenOcrString",
  "templateRaw": "base64TemplateRawString",
  "documentCode": "E1234V",
  "documentNumber": "1234567890",
  "countryCode": "ECU",
  "returnPII": true,
  "tracking": {
    "extraData": "BQABAQG2gBNjuHN...",
    "operationId": "xxxxx-xxxxx-xxxxx-xxxxx-xxxxx"
  }
}
```

### Responses

#### `200` Success

#### Response parameters

| Parameter                           | Type    | Description                                                                                                                                  |
| ----------------------------------- | ------- | -------------------------------------------------------------------------------------------------------------------------------------------- |
| `serviceResultCode`                 | integer | Code that indicates the overall result of the service execution. See [Service Result Code](#service-result-code).                            |
| `serviceTime`                       | string  | Total processing time (milliseconds).                                                                                                        |
| `serviceResultLog`                  | string  | Descriptive field for the result of the service execution. Includes details when there is an error or exception.                             |
| `serviceTransactionId`              | string  | Transaction identifier associated with the request processed by the API.                                                                     |
| `civilDataValidation`               | array   | Array that represents OCR validations against the data obtained from the Civil Registry. Its presence depends on the Civil Registry queried. |
| `civilDataValidation[].field`       | string  | Name of the validated field (e.g., `firstName`, `lastName`, `dateOfBirth`).                                                                  |
| `civilDataValidation[].code`        | string  | Validation result code. `"0"`: Validated correctly. `"-99"`: Possibly adulterated.                                                           |
| `civilDataValidation[].message`     | string  | Descriptive message of the validation result.                                                                                                |
| `serviceFacialAuthenticationResult` | integer | Code that indicates the result of facial matching. See [Service Facial Authentication Result](#service-facial-authentication-result).        |
| `serviceFacialSimilarityResult`     | number  | Value that indicates the facial similarity between the face in the document photo and the user's selfie. **1.0 = 100%**.                     |
| `serviceFacialAuthenticationHash`   | string  | Integrity hash of the biometric template used in a positive or uncertain facial authentication.                                              |
| `serviceDocument`                   | string  | JSON string that represents the captured document. Its properties are all the fields extracted by the OCR process.                           |
| `civilServiceData`                  | string  | JSON string with the personal data obtained from the Civil Registry (only returned if `returnPII` was sent as `true` in the request).        |

#### Response example

```json
{
  "serviceResultCode": 0,
  "serviceTime": "2500",
  "serviceResultLog": "Positive | Service executed ok",
  "serviceTransactionId": "12345678-1234-1234-1234-123456789012",
  "civilDataValidation": [
    {
      "field": "dateOfBirth",
      "code": "0",
      "message": "Validated ok"
    },
    {
      "field": "firstName",
      "code": "0",
      "message": "Validated ok"
    },
    {
      "field": "lastName",
      "code": "0",
      "message": "Validated ok"
    }
  ],
  "serviceFacialAuthenticationResult": 3,
  "serviceFacialSimilarityResult": 0.98,
  "serviceFacialAuthenticationHash": "ABC123DEF456GHI789JKL012MNO345PQR678STU901VWX234YZ567",
  "serviceDocument": "{\"DocumentNumber\":\"1234567890\",\"FirstName\":\"JUAN CARLOS\",\"LastName\":\"RODRIGUEZ LOPEZ\",\"DateOfBirth\":\"15/03/1985\",\"Gender\":\"M\",\"Nationality\":\"ECUATORIANA\"}",
  "civilServiceData": "{\"apellidos\":\"RODRIGUEZ LOPEZ\",\"nombres\":\"JUAN CARLOS\",\"fechaNacimiento\":\"15/03/1985\",\"sexo\":\"HOMBRE\",\"nacionalidad\":\"ECUATORIANA\",\"estadoCivil\":\"SOLTERO\"}"
}
```

## Full Validation Web

Performs data validation and facial matching against Ecuador's Civil Registry using the web platform.

### Request body

**Content-Type:** `application/json`

#### Parameters

| Parameter              | Type    | Required | Description                                                                                                                   |
| ---------------------- | ------- | -------- | ----------------------------------------------------------------------------------------------------------------------------- |
| `operation`            | string  | **Yes**  | Validation operation to perform. Value: `"FULL"`.                                                                             |
| `platform`             | string  | **Yes**  | Platform from which the request is made. Value: `"WEB"`.                                                                      |
| `imageFrontDocument`   | string  | **Yes**  | Front capture of the document, image in Base64 without the MIME type header. Required for the WEB platform.                   |
| `imageBackDocument`    | string  | **Yes**  | Back capture of the document, image in Base64 without the MIME type header. Required for the WEB platform.                    |
| `templateRaw`          | string  | **Yes**  | Biometric Template generated by the Selphi Widget. Required for FACIAL or FULL operations.                                    |
| `documentCode`         | string  | **Yes**  | Document code (fingerprintCode), required for validation in Ecuador.                                                          |
| `documentNumber`       | string  | No       | User's document number.                                                                                                       |
| `countryCode`          | string  | **Yes**  | Country code in ISO 3166-1 alpha-3 format. Value: `"ECU"`.                                                                    |
| `returnPII`            | boolean | No       | Indicates whether the personal data generated by the OCR service and the response from the Civil Registry should be returned. |
| `documentValidation`   | boolean | No       | Indicates whether document validation should be started, returning `scanReference` and `type`.                                |
| `tracking`             | object  | No       | Object that represents the necessary tracking information.                                                                    |
| `tracking.extraData`   | string  | No       | Token generated by the Mobile/Web SDK. Contains tokenized tracking information with the Platform.                             |
| `tracking.operationId` | string  | No       | Operation identifier generated by the Mobile/Web SDK.                                                                         |

#### Request example

```json
{
  "operation": "FULL",
  "platform": "WEB",
  "imageFrontDocument": "base64ImageFrontString",
  "imageBackDocument": "base64ImageBackString",
  "templateRaw": "base64TemplateRawString",
  "documentNumber": "0987654321",
  "documentCode": "V5678V",
  "countryCode": "ECU",
  "returnPII": true,
  "tracking": {
    "extraData": "BQABAQG2gBNjuHN...",
    "operationId": "xxxxx-xxxxx-xxxxx-xxxxx-xxxxx"
  }
}
```

### Responses

#### `200` Success

#### Response parameters

| Parameter                           | Type    | Description                                                                                                                                  |
| ----------------------------------- | ------- | -------------------------------------------------------------------------------------------------------------------------------------------- |
| `serviceResultCode`                 | integer | Code that indicates the overall result of the service execution. See [Service Result Code](#service-result-code).                            |
| `serviceTime`                       | string  | Total processing time (milliseconds).                                                                                                        |
| `serviceResultLog`                  | string  | Descriptive field for the result of the service execution. Includes details when there is an error or exception.                             |
| `serviceTransactionId`              | string  | Transaction identifier associated with the request processed by the API.                                                                     |
| `civilDataValidation`               | array   | Array that represents OCR validations against the data obtained from the Civil Registry. Its presence depends on the Civil Registry queried. |
| `civilDataValidation[].field`       | string  | Name of the validated field (e.g., `firstName`, `lastName`, `dateOfBirth`).                                                                  |
| `civilDataValidation[].code`        | string  | Validation result code. `"0"`: Validated correctly. `"-99"`: Possibly adulterated.                                                           |
| `civilDataValidation[].message`     | string  | Descriptive message of the validation result.                                                                                                |
| `serviceFacialAuthenticationResult` | integer | Code that indicates the result of facial matching. See [Service Facial Authentication Result](#service-facial-authentication-result).        |
| `serviceFacialSimilarityResult`     | number  | Value that indicates the facial similarity between the face in the document photo and the user's selfie. **1.0 = 100%**.                     |
| `serviceFacialAuthenticationHash`   | string  | Integrity hash of the biometric template used in a positive or uncertain facial authentication.                                              |
| `serviceDocument`                   | string  | JSON string that represents the captured document. Its properties are all the fields extracted by the OCR process.                           |
| `civilServiceData`                  | string  | JSON string with the personal data obtained from the Civil Registry (only returned if `returnPII` was sent as `true` in the request).        |

#### Response example

```json
{
  "serviceResultCode": 0,
  "serviceTime": "3200",
  "serviceResultLog": "Negative | Service executed ok",
  "serviceTransactionId": "87654321-4321-4321-4321-210987654321",
  "civilDataValidation": [],
  "serviceFacialAuthenticationResult": 1,
  "serviceFacialSimilarityResult": 0.15,
  "serviceFacialAuthenticationHash": "ZYX987WVU654TSR321PON098MLK765JIH432GFE109DCB876A543",
  "serviceDocument": "{\"DocumentNumber\":\"0987654321\",\"FirstName\":\"MARIA ELENA\",\"LastName\":\"GONZALEZ TORRES\",\"DateOfBirth\":\"28/11/1992\",\"Gender\":\"F\",\"Nationality\":\"ECUATORIANA\"}",
  "civilServiceData": "{\"apellidos\":\"GONZALEZ TORRES\",\"nombres\":\"MARIA ELENA\",\"fechaNacimiento\":\"28/11/1992\",\"sexo\":\"MUJER\",\"nacionalidad\":\"ECUATORIANA\",\"estadoCivil\":\"CASADO\"}"
}
```

## Data Validation Mobile

Performs data validation against Ecuador's Civil Registry using the web platform. Does not include facial matching.

### Request body

**Content-Type:** `application/json`

#### Parameters

| Parameter              | Type    | Required | Description                                                                                                                                                                     |
| ---------------------- | ------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `operation`            | string  | **Yes**  | Validation operation to perform. Value: `"DATA"`.                                                                                                                               |
| `platform`             | string  | **Yes**  | Platform from which the request is made. Value: `"MOBILE"`.                                                                                                                     |
| `tokenOcr`             | string  | **Yes**  | Token generated by the native or hybrid SelphID Widget, encrypted in AES256 and Tokenized, sent in Base64 format. It contains the OCR result of the captured Identity document. |
| `documentCode`         | string  | **Yes**  | Document code (fingerprintCode), required for validation in Ecuador.                                                                                                            |
| `documentNumber`       | string  | No       | User's document number.                                                                                                                                                         |
| `countryCode`          | string  | **Yes**  | Country code in ISO 3166-1 alpha-3 format. Value: `"ECU"`.                                                                                                                      |
| `returnPII`            | boolean | No       | Indicates whether the personal data generated by the OCR service and the response from the Civil Registry should be returned.                                                   |
| `documentValidation`   | boolean | No       | Indicates whether document validation should be started, returning `scanReference` and `type`.                                                                                  |
| `tracking`             | object  | No       | Object that represents the necessary tracking information.                                                                                                                      |
| `tracking.extraData`   | string  | No       | Token generated by the Mobile/Web SDK. Contains tokenized tracking information with the Platform.                                                                               |
| `tracking.operationId` | string  | No       | Operation identifier generated by the Mobile/Web SDK.                                                                                                                           |

#### Request example

```json
{
  "operation": "DATA",
  "platform": "MOBILE",
  "tokenOcr": "base64TokenOcrString",
  "documentCode": "E9876V",
  "documentNumber": "1122334455",
  "countryCode": "ECU",
  "returnPII": true,
  "tracking": {
    "extraData": "BQABAQG2gBNjuHN...",
    "operationId": "xxxxx-xxxxx-xxxxx-xxxxx-xxxxx"
  }
}
```

### Responses

#### `200` Success

#### Response parameters

| Parameter                       | Type    | Description                                                                                                                                  |
| ------------------------------- | ------- | -------------------------------------------------------------------------------------------------------------------------------------------- |
| `serviceResultCode`             | integer | Code that indicates the overall result of the service execution. See [Service Result Code](#service-result-code).                            |
| `serviceTime`                   | string  | Total processing time (milliseconds).                                                                                                        |
| `serviceResultLog`              | string  | Descriptive field for the result of the service execution. Includes details when there is an error or exception.                             |
| `serviceTransactionId`          | string  | Transaction identifier associated with the request processed by the API.                                                                     |
| `civilDataValidation`           | array   | Array that represents OCR validations against the data obtained from the Civil Registry. Its presence depends on the Civil Registry queried. |
| `civilDataValidation[].field`   | string  | Name of the validated field (e.g., `firstName`, `lastName`, `dateOfBirth`).                                                                  |
| `civilDataValidation[].code`    | string  | Validation result code. `"0"`: Validated correctly. `"-99"`: Possibly adulterated.                                                           |
| `civilDataValidation[].message` | string  | Descriptive message of the validation result.                                                                                                |
| `serviceDocument`               | string  | JSON string that represents the captured document. Its properties are all the fields extracted by the OCR process.                           |
| `civilServiceData`              | string  | JSON string with the personal data obtained from the Civil Registry (only returned if `returnPII` was sent as `true` in the request).        |

#### Response example

```json
{
  "serviceResultCode": 0,
  "serviceTime": "1800",
  "serviceResultLog": "Service executed ok",
  "serviceTransactionId": "55443322-5544-3322-1100-554433221100",
  "civilDataValidation": [
    {
      "field": "dateOfBirth",
      "code": "0",
      "message": "Validated ok"
    },
    {
      "field": "firstName",
      "code": "0",
      "message": "Validated ok"
    },
    {
      "field": "lastName",
      "code": "0",
      "message": "Validated ok"
    }
  ],
  "serviceDocument": "{\"DocumentNumber\":\"1122334455\",\"FirstName\":\"CARLOS ALBERTO\",\"LastName\":\"MARTINEZ SILVA\",\"DateOfBirth\":\"10/07/1978\",\"Gender\":\"M\",\"Nationality\":\"ECUATORIANA\"}",
  "civilServiceData": "{\"apellidos\":\"MARTINEZ SILVA\",\"nombres\":\"CARLOS ALBERTO\",\"fechaNacimiento\":\"10/07/1978\",\"sexo\":\"HOMBRE\",\"nacionalidad\":\"ECUATORIANA\",\"estadoCivil\":\"DIVORCIADO\"}"
}
```

## Data Validation Web

Performs data validation against Ecuador's Civil Registry using the web platform. Does not include facial matching.

### Request body

**Content-Type:** `application/json`

#### Parameters

| Parameter              | Type    | Required | Description                                                                                                                   |
| ---------------------- | ------- | -------- | ----------------------------------------------------------------------------------------------------------------------------- |
| `operation`            | string  | **Yes**  | Validation operation to perform. Value: `"DATA"`.                                                                             |
| `platform`             | string  | **Yes**  | Platform from which the request is made. Value: `"WEB"`.                                                                      |
| `imageFrontDocument`   | string  | **Yes**  | Front capture of the document, image in Base64 without the MIME type header. Required for the WEB platform.                   |
| `imageBackDocument`    | string  | **Yes**  | Back capture of the document, image in Base64 without the MIME type header. Required for the WEB platform.                    |
| `documentCode`         | string  | **Yes**  | Document code (fingerprintCode), required for validation in Ecuador.                                                          |
| `countryCode`          | string  | **Yes**  | Country code in ISO 3166-1 alpha-3 format. Value: `"ECU"`.                                                                    |
| `returnPII`            | boolean | No       | Indicates whether the personal data generated by the OCR service and the response from the Civil Registry should be returned. |
| `documentValidation`   | boolean | No       | Indicates whether document validation should be started, returning `scanReference` and `type`.                                |
| `tracking`             | object  | No       | Object that represents the necessary tracking information.                                                                    |
| `tracking.extraData`   | string  | No       | Token generated by the Mobile/Web SDK. Contains tokenized tracking information with the Platform.                             |
| `tracking.operationId` | string  | No       | Operation identifier generated by the Mobile/Web SDK.                                                                         |

#### Request example

```json
{
  "operation": "DATA",
  "platform": "WEB",
  "documentCode": "V1357V",
  "imageFrontDocument": "base64ImageFrontString",
  "imageBackDocument": "base64ImageBackString",
  "countryCode": "ECU",
  "returnPII": true,
  "tracking": {
    "extraData": "BQABAQG2gBNjuHN...",
    "operationId": "xxxxx-xxxxx-xxxxx-xxxxx-xxxxx"
  }
}
```

### Responses

#### `200` Success

#### Response parameters

| Parameter                       | Type    | Description                                                                                                                                  |
| ------------------------------- | ------- | -------------------------------------------------------------------------------------------------------------------------------------------- |
| `serviceResultCode`             | integer | Code that indicates the overall result of the service execution. See [Service Result Code](#service-result-code).                            |
| `serviceTime`                   | string  | Total processing time (milliseconds).                                                                                                        |
| `serviceResultLog`              | string  | Descriptive field for the result of the service execution. Includes details when there is an error or exception.                             |
| `serviceTransactionId`          | string  | Transaction identifier associated with the request processed by the API.                                                                     |
| `civilDataValidation`           | array   | Array that represents OCR validations against the data obtained from the Civil Registry. Its presence depends on the Civil Registry queried. |
| `civilDataValidation[].field`   | string  | Name of the validated field (e.g., `firstName`, `lastName`, `dateOfBirth`).                                                                  |
| `civilDataValidation[].code`    | string  | Validation result code. `"0"`: Validated correctly. `"-99"`: Possibly adulterated.                                                           |
| `civilDataValidation[].message` | string  | Descriptive message of the validation result.                                                                                                |
| `serviceDocument`               | string  | JSON string that represents the captured document. Its properties are all the fields extracted by the OCR process.                           |
| `civilServiceData`              | string  | JSON string with the personal data obtained from the Civil Registry (only returned if `returnPII` was sent as `true` in the request).        |

#### Response example

```json
{
  "serviceResultCode": 0,
  "serviceTime": "2100",
  "serviceResultLog": "Service executed ok",
  "serviceTransactionId": "13579246-1357-9246-8024-135792468024",
  "civilDataValidation": [
    {
      "field": "firstName",
      "code": "-99",
      "message": "Possibly adulterated"
    },
    {
      "field": "lastName",
      "code": "0",
      "message": "Validated ok"
    },
    {
      "field": "dateOfBirth",
      "code": "0",
      "message": "Validated ok"
    }
  ],
  "serviceDocument": "{\"DocumentNumber\":\"2468135790\",\"FirstName\":\"ANA PATRICIA\",\"LastName\":\"LOPEZ HERRERA\",\"DateOfBirth\":\"22/09/1990\",\"Gender\":\"F\",\"Nationality\":\"ECUATORIANA\"}"
}
```

## Facial Validation Mobile

Performs facial matching against the official images of Ecuador's Civil Registry using the mobile platform. Does not include data validation.

### Request body

**Content-Type:** `application/json`

#### Parameters

| Parameter              | Type   | Required | Description                                                                                       |
| ---------------------- | ------ | -------- | ------------------------------------------------------------------------------------------------- |
| `operation`            | string | **Yes**  | Validation operation to perform. Value: `"FACIAL"`.                                               |
| `platform`             | string | **Yes**  | Platform from which the request is made. Value: `"MOBILE"`.                                       |
| `templateRaw`          | string | **Yes**  | Biometric Template generated by the Selphi Widget. Required for FACIAL or FULL operations.        |
| `documentNumber`       | string | No       | User's document number. Required for FACIAL operations.                                           |
| `documentCode`         | string | **Yes**  | Document code (fingerprintCode), required for validation in Ecuador.                              |
| `countryCode`          | string | **Yes**  | Country code in ISO 3166-1 alpha-3 format. Value: `"ECU"`.                                        |
| `tracking`             | object | No       | Object that represents the necessary tracking information.                                        |
| `tracking.extraData`   | string | No       | Token generated by the Mobile/Web SDK. Contains tokenized tracking information with the Platform. |
| `tracking.operationId` | string | No       | Operation identifier generated by the Mobile/Web SDK.                                             |

#### Request example

```json
{
  "operation": "FACIAL",
  "platform": "MOBILE",
  "documentNumber": "9876543210",
  "documentCode": "V2468V",
  "templateRaw": "base64TemplateRawString",
  "countryCode": "ECU",
  "tracking": {
    "extraData": "BQABAQG2gBNjuHN...",
    "operationId": "xxxxx-xxxxx-xxxxx-xxxxx-xxxxx"
  }
}
```

### Responses

#### `200` Success

#### Response parameters

| Parameter                           | Type    | Description                                                                                                                                  |
| ----------------------------------- | ------- | -------------------------------------------------------------------------------------------------------------------------------------------- |
| `serviceResultCode`                 | integer | Code that indicates the overall result of the service execution. See [Service Result Code](#service-result-code).                            |
| `serviceTime`                       | string  | Total processing time (milliseconds).                                                                                                        |
| `serviceResultLog`                  | string  | Descriptive field for the result of the service execution. Includes details when there is an error or exception.                             |
| `serviceTransactionId`              | string  | Transaction identifier associated with the request processed by the API.                                                                     |
| `civilDataValidation`               | array   | Array that represents OCR validations against the data obtained from the Civil Registry. Its presence depends on the Civil Registry queried. |
| `civilDataValidation[].field`       | string  | Name of the validated field (e.g., `firstName`, `lastName`, `dateOfBirth`).                                                                  |
| `civilDataValidation[].code`        | string  | Validation result code. `"0"`: Validated correctly. `"-99"`: Possibly adulterated.                                                           |
| `civilDataValidation[].message`     | string  | Descriptive message of the validation result.                                                                                                |
| `serviceFacialAuthenticationResult` | integer | Code that indicates the result of facial matching. See [Service Facial Authentication Result](#service-facial-authentication-result).        |
| `serviceFacialSimilarityResult`     | number  | Value that indicates the facial similarity between the face in the document photo and the user's selfie. **1.0 = 100%**.                     |
| `serviceFacialAuthenticationHash`   | string  | Integrity hash of the biometric template used in a positive or uncertain facial authentication.                                              |
| `serviceDocument`                   | string  | JSON string that represents the captured document. Its properties are all the fields extracted by the OCR process.                           |

#### Response example

```json
{
  "serviceResultCode": 0,
  "serviceTime": "2800",
  "serviceResultLog": "Positive | Service executed ok",
  "serviceTransactionId": "24681357-2468-1357-9024-246813579024",
  "civilDataValidation": [
    {
      "field": "firstName",
      "code": "-99",
      "message": "Possibly adulterated"
    },
    {
      "field": "lastName",
      "code": "0",
      "message": "Validated ok"
    },
    {
      "field": "dateOfBirth",
      "code": "0",
      "message": "Validated ok"
    }
  ],
  "serviceFacialAuthenticationResult": 3,
  "serviceFacialSimilarityResult": 0.94,
  "serviceFacialAuthenticationHash": "DEF789GHI012JKL345MNO678PQR901STU234VWX567YZA890BCD123",
  "serviceDocument": "{\"DocumentNumber\":\"9876543210\",\"FirstName\":\"LUIS FERNANDO\",\"LastName\":\"PEREZ CASTRO\",\"DateOfBirth\":\"05/12/1986\",\"Gender\":\"M\",\"Nationality\":\"ECUATORIANA\"}"
}
```

## Facial Validation Web

Performs facial matching against the official images of Ecuador's Civil Registry using the web platform. Does not include data validation.

### Request body

**Content-Type:** `application/json`

#### Parameters

| Parameter              | Type    | Required | Description                                                                                       |
| ---------------------- | ------- | -------- | ------------------------------------------------------------------------------------------------- |
| `operation`            | string  | **Yes**  | Validation operation to perform. Value: `"FACIAL"`.                                               |
| `platform`             | string  | **Yes**  | Platform from which the request is made. Value: `"WEB"`.                                          |
| `templateRaw`          | string  | **Yes**  | Biometric Template generated by the Selphi Widget. Required for FACIAL or FULL operations.        |
| `documentCode`         | string  | **Yes**  | Document code (fingerprintCode), required for validation in Ecuador.                              |
| `documentNumber`       | string  | **Yes**  | User's document number. Required for FACIAL operations.                                           |
| `countryCode`          | string  | **Yes**  | Country code in ISO 3166-1 alpha-3 format. Value: `"ECU"`.                                        |
| `returnPII`            | boolean | No       | Indicates whether the personal data generated by the Civil Registry response should be received.  |
| `tracking`             | object  | No       | Object that represents the necessary tracking information.                                        |
| `tracking.extraData`   | string  | No       | Token generated by the Mobile/Web SDK. Contains tokenized tracking information with the Platform. |
| `tracking.operationId` | string  | No       | Operation identifier generated by the Mobile/Web SDK.                                             |

#### Request example

```json
{
  "operation": "FACIAL",
  "platform": "WEB",
  "templateRaw": "base64TemplateRawString",
  "documentCode": "E8642I",
  "documentNumber": "5678901234",
  "countryCode": "ECU",
  "returnPII": true,
  "tracking": {
    "extraData": "BQABAQG2gBNjuHN...",
    "operationId": "xxxxx-xxxxx-xxxxx-xxxxx-xxxxx"
  }
}
```

### Responses

#### `200` Success

#### Response parameters

| Parameter                           | Type    | Description                                                                                                                                  |
| ----------------------------------- | ------- | -------------------------------------------------------------------------------------------------------------------------------------------- |
| `serviceResultCode`                 | integer | Code that indicates the overall result of the service execution. See [Service Result Code](#service-result-code).                            |
| `serviceTime`                       | string  | Total processing time (milliseconds).                                                                                                        |
| `serviceResultLog`                  | string  | Descriptive field for the result of the service execution. Includes details when there is an error or exception.                             |
| `serviceTransactionId`              | string  | Transaction identifier associated with the request processed by the API.                                                                     |
| `civilDataValidation`               | array   | Array that represents OCR validations against the data obtained from the Civil Registry. Its presence depends on the Civil Registry queried. |
| `civilDataValidation[].field`       | string  | Name of the validated field (e.g., `firstName`, `lastName`, `dateOfBirth`).                                                                  |
| `civilDataValidation[].code`        | string  | Validation result code. `"0"`: Validated correctly. `"-99"`: Possibly adulterated.                                                           |
| `civilDataValidation[].message`     | string  | Descriptive message of the validation result.                                                                                                |
| `serviceFacialAuthenticationResult` | integer | Code that indicates the result of facial matching. See [Service Facial Authentication Result](#service-facial-authentication-result).        |
| `serviceFacialSimilarityResult`     | number  | Value that indicates the facial similarity between the face in the document photo and the user's selfie. **1.0 = 100%**.                     |
| `serviceFacialAuthenticationHash`   | string  | Integrity hash of the biometric template used in a positive or uncertain facial authentication.                                              |
| `serviceDocument`                   | string  | JSON string that represents the captured document. Its properties are all the fields extracted by the OCR process.                           |
| `civilServiceData`                  | string  | JSON string with the personal data obtained from the Civil Registry (only returned if `returnPII` was sent as `true` in the request).        |

#### Response example

```json
{
  "serviceResultCode": 0,
  "serviceResultLog": "NoneBecausePoseExceed",
  "serviceTime": "1900",
  "serviceFacialAuthenticationResult": 4,
  "serviceFacialAuthenticationHash": "GHI456JKL789MNO012PQR345STU678VWX901YZA234BCD567EFG890",
  "serviceFacialSimilarityResult": 0.0,
  "serviceTransactionId": "86420135-8642-0135-7913-864201357913",
  "civilServiceData": "{\"apellidos\":\"RAMIREZ MORENO\",\"nombres\":\"SOFIA ALEXANDRA\",\"fechaNacimiento\":\"13/04/1995\",\"sexo\":\"MUJER\",\"nacionalidad\":\"ECUATORIANA\",\"estadoCivil\":\"SOLTERO\"}"
}
```

## Reference tables

#### Service Result Code

The `serviceResultCode` indicates the overall result of the service execution:

| serviceResultCode | Description                                                                       | HTTP code |
| ----------------- | --------------------------------------------------------------------------------- | --------- |
| 0                 | The service execution was successful, the module processed the request correctly. | 200       |

#### Service Facial Authentication Result

The `serviceFacialAuthenticationResult` indicates the result of facial matching operations (only for FULL and FACIAL operations):

| Code | Result                           | Description                                                                                                                                                                                         |
| ---- | -------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| 0    | NONE                             | Facial verification could not be performed.                                                                                                                                                         |
| 1    | NEGATIVE                         | The process was executed correctly. The facial pattern comparison of the faces does not match.                                                                                                      |
| 3    | POSITIVE                         | The process was executed correctly. The facial pattern comparison of the faces is positive. The value of `serviceFacialSimilarityResult` indicates the % of similarity between the compared images. |
| 4    | NONE BECAUSE POSE EXCEED         | Facial verification could not be performed due to the position of the face.                                                                                                                         |
| 5    | NONE BECAUSE INVALID EXTRACTIONS | Facial verification could not be performed due to problems extracting the facial pattern.                                                                                                           |

## Common errors

#### `400` Bad Request

```json
{
  "status": 400,
  "title": "Bad Request",
  "detail": "Invalid request.",
  "type": "https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/400",
  "errors": []
}
```

#### `401` Unauthorized

```json
{
  "message": "Unauthorized"
}
```

#### `403` Forbidden

```json
{
  "Message": "User is not authorized to access this resource with an explicit deny"
}
```

#### `502` Bad Gateway

```json
{
  "status": 502,
  "title": "Bad Gateway",
  "detail": "Server got an invalid response.",
  "type": "https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/502"
}
```

#### `504` Gateway Timeout

```json
{
  "message": "Endpoint request timed out"
}
```