> 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 data from Ecuador's Civil Registry.

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

### Endpoint

```
POST /services/civilValidation
```

### Headers

| Name          | Type   | Required | Description                                               |
| ------------- | ------ | -------- | --------------------------------------------------------- |
| **x-api-key** | string | **Yes**  | API key for access authorization.                         |
| **family**    | string | No       | Value: **Onboarding**. Required for the Tracking service. |

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

{% hint style="warning" %}
**Maximum request size: 6 MB.** The Base64 fields (`tokenOcr`, `imageFrontDocument`, `imageBackDocument` and `templateRaw`, depending on the operation and platform) count toward this limit together, with \~33% overhead compared to the original files (maximum \~4.5 MB of original files in total). Compressed JPEG images of no more than 1–2 MB each are recommended. If the limit is exceeded, the gateway responds `413` without processing the request. See [Request Size Limit](https://docs.facephi.com/pages/bc7bee9358079d52bafa44ad281828eb424e96fe#l%C3%ADmite-de-tama%C3%B1o-de-la-solicitud).
{% 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 with AES256 and Tokenized, sent in Base64 format. Contains the OCR result from 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 to receive the personal data generated by the OCR service and the Civil Registry response.                                                                     |
| `documentValidation`   | boolean | No       | Indicates whether to start document validation, returning `scanReference` and `type`.                                                                                            |
| `tracking`             | object  | No       | Object representing the required tracking information.                                                                                                                           |
| `tracking.extraData`   | string  | No       | Token generated by the SDK Mobile/Web. Contains tracking information tokenized with the Platform.                                                                                |
| `tracking.operationId` | string  | No       | Operation identifier generated by the SDK Mobile/Web.                                                                                                                            |

#### 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 indicating 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 an error or exception occurs.                              |
| `serviceTransactionId`              | string  | Transaction identifier associated with the request processed by the API.                                                                    |
| `civilDataValidation`               | array   | Array representing 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"`: Successfully validated. `"-99"`: Possibly tampered with.                                                     |
| `civilDataValidation[].message`     | string  | Descriptive message for the validation result.                                                                                              |
| `serviceFacialAuthenticationResult` | integer | Code indicating the facial matching result. See [Service Facial Authentication Result](#service-facial-authentication-result).              |
| `serviceFacialSimilarityResult`     | number  | Value indicating 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 representing the captured document. Its properties are all the fields extracted by the OCR process.                             |
| `civilServiceData`                  | string  | JSON string containing the personal data obtained from the Civil Registry (returned only if `returnPII` was sent as `true` in the request). |

#### Example response

```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 image of the document, Base64-encoded without the MIME type header. Required for the WEB platform.     |
| `imageBackDocument`    | string  | **Yes**  | Back of the document image, Base64 image 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 to receive the personal data generated by the OCR service and the Civil Registry response. |
| `documentValidation`   | boolean | No       | Indicates whether to start document validation, returning `scanReference` and `type`.                        |
| `tracking`             | object  | No       | Object representing the required tracking information.                                                       |
| `tracking.extraData`   | string  | No       | Token generated by the SDK Mobile/Web. Contains tracking information tokenized with the Platform.            |
| `tracking.operationId` | string  | No       | Operation identifier generated by the SDK Mobile/Web.                                                        |

#### 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 indicating 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 an error or exception occurs.                              |
| `serviceTransactionId`              | string  | Transaction identifier associated with the request processed by the API.                                                                    |
| `civilDataValidation`               | array   | Array representing 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"`: Successfully validated. `"-99"`: Possibly tampered with.                                                     |
| `civilDataValidation[].message`     | string  | Descriptive message for the validation result.                                                                                              |
| `serviceFacialAuthenticationResult` | integer | Code indicating the facial matching result. See [Service Facial Authentication Result](#service-facial-authentication-result).              |
| `serviceFacialSimilarityResult`     | number  | Value indicating 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 representing the captured document. Its properties are all the fields extracted by the OCR process.                             |
| `civilServiceData`                  | string  | JSON string containing the personal data obtained from the Civil Registry (returned only if `returnPII` was sent as `true` in the request). |

#### Example response

```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 mobile 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 with AES256 and Tokenized, sent in Base64 format. Contains the OCR result from 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 to receive the personal data generated by the OCR service and the Civil Registry response.                                                                     |
| `documentValidation`   | boolean | No       | Indicates whether to start document validation, returning `scanReference` and `type`.                                                                                            |
| `tracking`             | object  | No       | Object representing the required tracking information.                                                                                                                           |
| `tracking.extraData`   | string  | No       | Token generated by the SDK Mobile/Web. Contains tracking information tokenized with the Platform.                                                                                |
| `tracking.operationId` | string  | No       | Operation identifier generated by the SDK Mobile/Web.                                                                                                                            |

#### 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 indicating 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 an error or exception occurs.                              |
| `serviceTransactionId`          | string  | Transaction identifier associated with the request processed by the API.                                                                    |
| `civilDataValidation`           | array   | Array representing 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"`: Successfully validated. `"-99"`: Possibly tampered with.                                                     |
| `civilDataValidation[].message` | string  | Descriptive message for the validation result.                                                                                              |
| `serviceDocument`               | string  | JSON string representing the captured document. Its properties are all the fields extracted by the OCR process.                             |
| `civilServiceData`              | string  | JSON string containing the personal data obtained from the Civil Registry (returned only if `returnPII` was sent as `true` in the request). |

#### Example response

```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 image of the document, Base64-encoded without the MIME type header. Required for the WEB platform.     |
| `imageBackDocument`    | string  | **Yes**  | Back of the document image, Base64 image 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 to receive the personal data generated by the OCR service and the Civil Registry response. |
| `documentValidation`   | boolean | No       | Indicates whether to start document validation, returning `scanReference` and `type`.                        |
| `tracking`             | object  | No       | Object representing the required tracking information.                                                       |
| `tracking.extraData`   | string  | No       | Token generated by the SDK Mobile/Web. Contains tracking information tokenized with the Platform.            |
| `tracking.operationId` | string  | No       | Operation identifier generated by the SDK Mobile/Web.                                                        |

#### 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 indicating 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 an error or exception occurs.                              |
| `serviceTransactionId`          | string  | Transaction identifier associated with the request processed by the API.                                                                    |
| `civilDataValidation`           | array   | Array representing 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"`: Successfully validated. `"-99"`: Possibly tampered with.                                                     |
| `civilDataValidation[].message` | string  | Descriptive message for the validation result.                                                                                              |
| `serviceDocument`               | string  | JSON string representing the captured document. Its properties are all the fields extracted by the OCR process.                             |
| `civilServiceData`              | string  | JSON string containing the personal data obtained from the Civil Registry (returned only if `returnPII` was sent as `true` in the request). |

#### Example response

```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 official images from 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 representing the required tracking information.                                            |
| `tracking.extraData`   | string | No       | Token generated by the SDK Mobile/Web. Contains tracking information tokenized with the Platform. |
| `tracking.operationId` | string | No       | Operation identifier generated by the SDK Mobile/Web.                                             |

#### 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 indicating 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 an error or exception occurs.                            |
| `serviceTransactionId`              | string  | Transaction identifier associated with the request processed by the API.                                                                  |
| `civilDataValidation`               | array   | Array representing 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"`: Successfully validated. `"-99"`: Possibly tampered with.                                                   |
| `civilDataValidation[].message`     | string  | Descriptive message for the validation result.                                                                                            |
| `serviceFacialAuthenticationResult` | integer | Code indicating the facial matching result. See [Service Facial Authentication Result](#service-facial-authentication-result).            |
| `serviceFacialSimilarityResult`     | number  | Value indicating 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 representing the captured document. Its properties are all the fields extracted by the OCR process.                           |

#### Example response

```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 official images from 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 to receive the personal data generated by the Civil Registry response.          |
| `tracking`             | object  | No       | Object representing the required tracking information.                                            |
| `tracking.extraData`   | string  | No       | Token generated by the SDK Mobile/Web. Contains tracking information tokenized with the Platform. |
| `tracking.operationId` | string  | No       | Operation identifier generated by the SDK Mobile/Web.                                             |

#### 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 indicating 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 an error or exception occurs.                              |
| `serviceTransactionId`              | string  | Transaction identifier associated with the request processed by the API.                                                                    |
| `civilDataValidation`               | array   | Array representing 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"`: Successfully validated. `"-99"`: Possibly tampered with.                                                     |
| `civilDataValidation[].message`     | string  | Descriptive message for the validation result.                                                                                              |
| `serviceFacialAuthenticationResult` | integer | Code indicating the facial matching result. See [Service Facial Authentication Result](#service-facial-authentication-result).              |
| `serviceFacialSimilarityResult`     | number  | Value indicating 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 representing the captured document. Its properties are all the fields extracted by the OCR process.                             |
| `civilServiceData`                  | string  | JSON string containing the personal data obtained from the Civil Registry (returned only if `returnPII` was sent as `true` in the request). |

#### Example response

```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 (for FULL and FACIAL operations only):

| Code | Result                           | Description                                                                                                                                                                                  |
| ---- | -------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| 0    | NONE                             | Facial verification could not be performed.                                                                                                                                                  |
| 1    | NEGATIVE                         | The process completed successfully. The facial pattern comparison did not match.                                                                                                             |
| 3    | POSITIVE                         | The process completed successfully. The facial pattern comparison is positive. The value of `serviceFacialSimilarityResult` indicates the similarity percentage between the images compared. |
| 4    | NONE BECAUSE POSE EXCEED         | Facial verification could not be performed because of the face's pose.                                                                                                                       |
| 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"
}
```

#### `413` Payload Too Large

The request exceeds the maximum allowed size. The gateway rejects it **without processing it**: the response does not include `serviceResultCode` or `serviceTransactionId`. See [Request size limit](https://docs.facephi.com/pages/bc7bee9358079d52bafa44ad281828eb424e96fe#l%C3%ADmite-de-tama%C3%B1o-de-la-solicitud).

Request larger than 6 MB and up to 10 MB (`Content-Type: application/json`):

```json
{
  "message": "Request Too Long"
}
```

Request larger than 10 MB (10,485,760 bytes) (`Content-Type: text; charset=utf-8`, plain text, not JSON):

```
HTTP content length exceeded 10485760 bytes.
```

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