---
title: "Government Validation Module"
url: "https://developer.incode.com/sdk-reference/web-sdk-2-module-gov-validation-1/"
section: "sdk-reference"
group: "Incode Web SDK 2 Reference / Web SDK 2 Individual Modules"
version: "v1.1"
status: "live"
---
# Government Validation Module

:::note
This guide is specific to Web SDK 2.0. If you are still using 1.x, you can find documentation [here](/sdk-reference/web-sdk-reference).  Contact your Incode Representative for upgrade information and check if you are a candidate for this upgrade. <br /><br />Full rollout to all clients still TBD.
:::

The Government Validation module submits the user's identity data (typically post-ID-capture) to a government registry for verification. Multiple validation types can run simultaneously (facial, data, address) and OTP confirmation may be required for some country/regulator combinations.

The same module handles two flow variants that share one manager, state machine, and UI: `GOVT_VALIDATION_PROVISIONING` (the general government-registry check) and `INE_VALIDATION` (the Mexico INE check). The Mexico INE variant is the one that drives the OTP sub-loop (`awaitingOtp` / `verifyingOtp`). Both variants are configured from the dashboard flow, so most callers pass the config through unmodified.

> Follows a hybrid of the [backend-process pattern](/sdk-reference/web-sdk-2-module-patterns/#3-backend-process-modules) and the [form-based pattern](/sdk-reference/web-sdk-2-module-patterns/#1-form-based-modules) — backend-driven processing with an optional OTP sub-loop. See the patterns page for the shared lifecycle.

## Tag

`<incode-government-validation>` is a standard Web Component. Importing the UI subpath registers the custom element; importing the CSS applies the module's styles.

```ts
import '@incodetech/web/government-validation';
import '@incodetech/web/government-validation/styles.css';
```

For headless (no pre-built UI) control, drive it with `createGovernmentValidationManager` from `@incodetech/core/government-validation`. This module is typically invoked from an orchestrated flow rather than mounted standalone.

## Configuration

```typescript
type GovernmentValidationConfig = {
  validationCountries: string[];
  facialValidation: boolean;
  dataValidation: boolean;
  faceAndDataValidation: boolean;
  addressValidation: boolean;
  backgroundExecution: boolean;
  faceMatchOverrideDataScore: boolean;
  useCroppedIdFacePhoto: boolean;
  maxOtpAttempts?: number;
};
```

| Option                       | Type       | Required | Description                                                             |
| ---------------------------- | ---------- | -------- | ----------------------------------------------------------------------- |
| `validationCountries`        | `string[]` | ✅       | ISO country codes the backend should run against.                       |
| `facialValidation`           | `boolean`  | ✅       | Run facial validation (selfie ↔ government photo).                      |
| `dataValidation`             | `boolean`  | ✅       | Run data validation (name, DOB, etc.).                                  |
| `faceAndDataValidation`      | `boolean`  | ✅       | Combined face + data check.                                             |
| `addressValidation`          | `boolean`  | ✅       | Run address validation.                                                 |
| `backgroundExecution`        | `boolean`  | ✅       | When `true`, run silently without UI; advance via `onFinish`.           |
| `faceMatchOverrideDataScore` | `boolean`  | ✅       | Advanced: face-match score overrides data-score for the final decision. |
| `useCroppedIdFacePhoto`      | `boolean`  | ✅       | Use the cropped ID face photo (vs. full ID image).                      |
| `maxOtpAttempts`             | `number`   | ❌       | Max OTP attempts when OTP is required. Default `3`.                     |

### INE validation options

These options apply to the Mexican INE check. Set them on the module's dashboard configuration rather than in application code:

| Option                        | Type      | Required | Description                                                                                     |
| ----------------------------- | --------- | -------- | ----------------------------------------------------------------------------------------------- |
| `alternativeFacialValidation` | `boolean` | ❌        | Use the alternative facial-validation route for INE.                                            |
| `fallbackEnabled`             | `boolean` | ❌        | Allow the backend to fall back to another validation route when the primary one is unavailable. |
| `scrapingMethod`              | `boolean` | ❌        | Select the scraping-based INE validation route.                                                 |
| `scrapingV2`                  | `boolean` | ❌        | Select version 2 of the scraping route.                                                         |
| `scrapingV3`                  | `boolean` | ❌        | Select version 3 of the scraping route.                                                         |
| `failUnsupportedId`           | `boolean` | ❌        | Fail the module when the submitted document is not supported, instead of advancing.             |

These fields come from the dashboard's flow configuration. Most callers pass them through unmodified from the orchestrator's `state.config`.

## State machine

`GovernmentValidationState` is a discriminated union over `status`:

| Status           | Description                                                              |
| ---------------- | ------------------------------------------------------------------------ |
| `idle`           | Initial state.                                                           |
| `loading`        | Loading configuration / starting validation.                             |
| `processing`     | Backend validation in progress.                                          |
| `awaitingOtp`    | The chosen validation requires the user to confirm an OTP.               |
| `verifyingOtp`   | Verifying the submitted OTP.                                             |
| `displaySuccess` | Validation succeeded; the success result shows before the module finishes. |
| `unknown`        | Validation completed with an inconclusive result.                        |
| `finished`       | Terminal — validation accepted (or auto-skipped on a non-fatal failure). |
| `error`          | Fatal error.                                                             |

## API methods

Beyond the shared [backend-process](/sdk-reference/web-sdk-2-module-patterns/#3-backend-process-modules) set, this module owns the OTP step:

| Method             | Purpose                                | Callable when |
| ------------------ | -------------------------------------- | ------------- |
| `setOtpCode(code)` | Hold the code the user is typing.      | `awaitingOtp` |
| `validateOtp()`    | Submit the held code for verification. | `awaitingOtp` |
| `retry()`          | Retry after a failed validation.       | `error`       |

## See also

- [Module Patterns → backend-process](/sdk-reference/web-sdk-2-module-patterns/#3-backend-process-modules)
- [Module Patterns → form-based (OTP sub-loop)](/sdk-reference/web-sdk-2-module-patterns/#1-form-based-modules)
- [Individual Modules](/sdk-reference/web-sdk-2-individual-modules/)