> 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/nigeria.md).

# Nigeria

Civil validation service for Nigeria. Performs identity verification against data from the Nigerian Civil Registry.

### Endpoint

```
POST /services/civilValidation
```

### Headers

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

{% hint style="info" %}
All calls to the Tracking Endpoints with **Identity Platform** must include the `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 approximately 33% overhead compared to the original files (maximum of approximately 4.5 MB total for the original files). 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 the Nigerian 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.                                                                                       |
| `documentNumber`       | string  | No       | User's document number.                                                                                                                                                          |
| `countryCode`          | string  | **Yes**  | Country code in ISO 3166-1 alpha-3 format. Value: `"NGA"`.                                                                                                                       |
| `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.                                                                                                                            |

#### Example Request

```json
{
  "operation": "FULL",
  "platform": "MOBILE",
  "tokenOcr": "base64TokenOcrString",
  "templateRaw": "base64TemplateRawString",
  "documentNumber": "A00000001",
  "countryCode": "NGA",
  "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 match result. See [Service Facial Authentication Result](#service-facial-authentication-result).                 |
| `serviceFacialSimilarityResult`     | number  | Value indicating 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 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 (only returned if `returnPII` was sent as `true` in the request). |

#### Response example

```json
{
  "serviceResultCode": 0,
  "serviceTime": "2200",
  "serviceResultLog": "Positive | Service executed ok",
  "serviceTransactionId": "12345678-1234-1234-1234-123456789012",
  "civilDataValidation": [
    {
      "field": "firstName",
      "code": "0",
      "message": "Validated ok"
    },
    {
      "field": "lastName",
      "code": "0",
      "message": "Validated ok"
    },
    {
      "field": "dateOfBirth",
      "code": "0",
      "message": "Validated ok"
    }
  ],
  "serviceFacialAuthenticationResult": 3,
  "serviceFacialSimilarityResult": 0.97,
  "serviceFacialAuthenticationHash": "ABC123DEF456GHI789JKL012MNO345PQR678STU901VWX234YZ567",
  "serviceDocument": "{\"DocumentNumber\":\"A00000001\",\"FirstName\":\"ADEBAYO\",\"LastName\":\"OLADIPO\",\"DateOfBirth\":\"12/05/1988\",\"Gender\":\"M\",\"Nationality\":\"NIGERIAN\"}",
  "civilServiceData": "{\"surname\":\"OLADIPO\",\"firstName\":\"ADEBAYO\",\"dateOfBirth\":\"12/05/1988\",\"gender\":\"MALE\",\"nationality\":\"NIGERIAN\",\"maritalStatus\":\"SINGLE\"}"
}
```

## Full Validation Web

Performs data validation and facial matching against the Nigerian 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.                   |
| `documentNumber`       | string  | No       | User's document number.                                                                                      |
| `countryCode`          | string  | **Yes**  | Country code in ISO 3166-1 alpha-3 format. Value: `"NGA"`.                                                   |
| `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.                                                        |

#### Example Request

```json
{
  "operation": "FULL",
  "platform": "WEB",
  "imageFrontDocument": "base64ImageFrontString",
  "imageBackDocument": "base64ImageBackString",
  "templateRaw": "base64TemplateRawString",
  "documentNumber": "A00000002",
  "countryCode": "NGA",
  "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 match result. See [Service Facial Authentication Result](#service-facial-authentication-result).                 |
| `serviceFacialSimilarityResult`     | number  | Value indicating 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 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 (only returned if `returnPII` was sent as `true` in the request). |

#### Response example

```json
{
  "serviceResultCode": 0,
  "serviceTime": "3500",
  "serviceResultLog": "Negative | Service executed ok",
  "serviceTransactionId": "98765432-9876-5432-1098-987654321098",
  "civilDataValidation": [],
  "serviceFacialAuthenticationResult": 1,
  "serviceFacialSimilarityResult": 0.12,
  "serviceFacialAuthenticationHash": "ZYX987WVU654TSR321QPO098NML765KJI432HGF109EDC876BAZ543",
  "serviceDocument": "{\"DocumentNumber\":\"A00000002\",\"FirstName\":\"CHINONSO EMEKA\",\"LastName\":\"OKONKWO\",\"DateOfBirth\":\"08/11/1993\",\"Gender\":\"M\",\"Nationality\":\"NIGERIAN\"}",
  "civilServiceData": "{\"surname\":\"OKONKWO\",\"firstName\":\"CHINONSO EMEKA\",\"dateOfBirth\":\"08/11/1993\",\"gender\":\"MALE\",\"nationality\":\"NIGERIAN\",\"maritalStatus\":\"MARRIED\"}"
}
```

## Data Validation Mobile

Performs data validation against the Nigerian Civil Registry using a 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. |
| `documentNumber`       | string  | No       | User's document number.                                                                                                                                                          |
| `countryCode`          | string  | **Yes**  | Country code in ISO 3166-1 alpha-3 format. Value: `"NGA"`.                                                                                                                       |
| `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.                                                                                                                            |

#### Example Request

```json
{
  "operation": "DATA",
  "platform": "MOBILE",
  "tokenOcr": "base64TokenOcrString",
  "documentNumber": "B12345678",
  "countryCode": "NGA",
  "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 (only returned if `returnPII` was sent as `true` in the request). |

#### Response example

```json
{
  "serviceResultCode": 0,
  "serviceTime": "1600",
  "serviceResultLog": "Service executed ok",
  "serviceTransactionId": "55443322-5544-3322-1100-554433221100",
  "civilDataValidation": [
    {
      "field": "firstName",
      "code": "0",
      "message": "Validated ok"
    },
    {
      "field": "lastName",
      "code": "0",
      "message": "Validated ok"
    },
    {
      "field": "dateOfBirth",
      "code": "0",
      "message": "Validated ok"
    }
  ],
  "serviceDocument": "{\"DocumentNumber\":\"B12345678\",\"FirstName\":\"OLUWASEUN TUNDE\",\"LastName\":\"AFOLABI\",\"DateOfBirth\":\"23/01/1985\",\"Gender\":\"M\",\"Nationality\":\"NIGERIAN\"}",
  "civilServiceData": "{\"surname\":\"AFOLABI\",\"firstName\":\"OLUWASEUN TUNDE\",\"dateOfBirth\":\"23/01/1985\",\"gender\":\"MALE\",\"nationality\":\"NIGERIAN\",\"maritalStatus\":\"MARRIED\"}"
}
```

## Data Validation Web

Performs data validation against the Nigerian Civil Registry using a 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.   |
| `countryCode`          | string  | **Yes**  | Country code in ISO 3166-1 alpha-3 format. Value: `"NGA"`.                                                   |
| `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.                                                        |

#### Example Request

```json
{
  "operation": "DATA",
  "platform": "WEB",
  "imageFrontDocument": "base64ImageFrontString",
  "imageBackDocument": "base64ImageBackString",
  "countryCode": "NGA",
  "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 (only returned if `returnPII` was sent as `true` in the request). |

#### Response example

```json
{
  "serviceResultCode": 0,
  "serviceTime": "2300",
  "serviceResultLog": "Service executed ok",
  "serviceTransactionId": "66778899-6677-8899-0011-667788990011",
  "civilDataValidation": [
    {
      "field": "firstName",
      "code": "0",
      "message": "Validated ok"
    },
    {
      "field": "lastName",
      "code": "-99",
      "message": "Possibly adulterated"
    },
    {
      "field": "dateOfBirth",
      "code": "0",
      "message": "Validated ok"
    }
  ],
  "serviceDocument": "{\"DocumentNumber\":\"C44556677\",\"FirstName\":\"NGOZI AMARA\",\"LastName\":\"EZE\",\"DateOfBirth\":\"17/09/1991\",\"Gender\":\"F\",\"Nationality\":\"NIGERIAN\"}",
  "civilServiceData": "{\"surname\":\"EZE\",\"firstName\":\"NGOZI AMARA\",\"dateOfBirth\":\"17/09/1991\",\"gender\":\"FEMALE\",\"nationality\":\"NIGERIAN\",\"maritalStatus\":\"SINGLE\"}"
}
```

## Facial Validation Mobile

Performs facial matching against official images in the Nigerian Civil Registry using a 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 | **Yes**  | User's document number. Required for FACIAL operations.                                           |
| `countryCode`          | string | **Yes**  | Country code in ISO 3166-1 alpha-3 format. Value: `"NGA"`.                                        |
| `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.                                             |

#### Example Request

```json
{
  "operation": "FACIAL",
  "platform": "MOBILE",
  "templateRaw": "base64TemplateRawString",
  "documentNumber": "C98765432",
  "countryCode": "NGA",
  "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 match result. See [Service Facial Authentication Result](#service-facial-authentication-result).                 |
| `serviceFacialSimilarityResult`     | number  | Value indicating 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 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 (only returned if `returnPII` was sent as `true` in the request). |

#### Response example

```json
{
  "serviceResultCode": 0,
  "serviceTime": "2600",
  "serviceResultLog": "Positive | Service executed ok",
  "serviceTransactionId": "24681357-2468-1357-9024-246813579024",
  "serviceFacialAuthenticationResult": 3,
  "serviceFacialSimilarityResult": 0.95,
  "serviceFacialAuthenticationHash": "DEF789GHI012JKL345MNO678PQR901STU234VWX567YZA890BCD123",
  "serviceDocument": "{\"DocumentNumber\":\"C98765432\",\"FirstName\":\"IFEANYI CHUKWUEMEKA\",\"LastName\":\"NWOSU\",\"DateOfBirth\":\"05/12/1986\",\"Gender\":\"M\",\"Nationality\":\"NIGERIAN\"}",
  "civilServiceData": "{\"surname\":\"NWOSU\",\"firstName\":\"IFEANYI CHUKWUEMEKA\",\"dateOfBirth\":\"05/12/1986\",\"gender\":\"MALE\",\"nationality\":\"NIGERIAN\",\"maritalStatus\":\"MARRIED\"}"
}
```

## Facial Validation Web

Performs facial matching against official images in the Nigerian Civil Registry using a 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.        |
| `documentNumber`       | string  | **Yes**  | User's document number. Required for FACIAL operations.                                           |
| `countryCode`          | string  | **Yes**  | Country code in ISO 3166-1 alpha-3 format. Value: `"NGA"`.                                        |
| `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.                                             |

#### Example Request

```json
{
  "operation": "FACIAL",
  "platform": "WEB",
  "templateRaw": "base64TemplateRawString",
  "documentNumber": "D55667788",
  "countryCode": "NGA",
  "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 match result. See [Service Facial Authentication Result](#service-facial-authentication-result).                 |
| `serviceFacialSimilarityResult`     | number  | Value indicating 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 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 (only returned if `returnPII` was sent as `true` in the request). |

#### Response example

```json
{
  "serviceResultCode": 0,
  "serviceTime": "2000",
  "serviceResultLog": "NoneBecausePoseExceed",
  "serviceTransactionId": "13579024-1357-9024-6802-135790246802",
  "serviceFacialAuthenticationResult": 4,
  "serviceFacialSimilarityResult": 0.0,
  "serviceFacialAuthenticationHash": "GHI456JKL789MNO012PQR345STU678VWX901YZA234BCD567EFG890",
  "serviceDocument": "{\"DocumentNumber\":\"D55667788\",\"FirstName\":\"AISHA FATIMA\",\"LastName\":\"BELLO\",\"DateOfBirth\":\"30/07/1994\",\"Gender\":\"F\",\"Nationality\":\"NIGERIAN\"}",
  "civilServiceData": "{\"surname\":\"BELLO\",\"firstName\":\"AISHA FATIMA\",\"dateOfBirth\":\"30/07/1994\",\"gender\":\"FEMALE\",\"nationality\":\"NIGERIAN\",\"maritalStatus\":\"SINGLE\"}"
}
```

## 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 the facial matching operations (only for FULL and FACIAL operations):

| Code | Result                           | Description                                                                                                                                                                                                         |
| ---- | -------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| 0    | NONE                             | Facial verification could not be performed.                                                                                                                                                                         |
| 1    | NEGATIVE                         | The process completed successfully. The facial pattern comparison found no match between the faces.                                                                                                                 |
| 3    | POSITIVE                         | The process completed successfully. The facial pattern comparison found a match between the faces. The value of `serviceFacialSimilarityResult` indicates the percentage of similarity between the compared images. |
| 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 because of 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"
}
```
