---
title: "CURP Validation Module"
url: "https://developer.incode.com/sdk-reference/web-sdk-2-module-curp-validation/"
section: "sdk-reference"
group: "Incode Web SDK 2 Reference / Web SDK 2 Individual Modules"
version: "v1.1"
status: "live"
---
# CURP 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 CURP Validation module verifies a Mexican CURP (Clave Única de Registro de Población) — either by accepting the user's CURP and validating it server-side, or by generating one from the user's identity data when missing.

This module follows the [form-based pattern](/sdk-reference/web-sdk-2-module-patterns/#1-form-based-modules) with three input variants (enter, confirm, generate).

## Tag

`<incode-curp-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/curp-validation';
import '@incodetech/web/curp-validation/styles.css';
```

## Properties

| Property   | Type                      | Required | Description                      |
| ---------- | ------------------------- | -------- | -------------------------------- |
| `config`   | `CurpValidationConfig`    | ❌       | Configuration options            |
| `onFinish` | `() => void`              | ❌       | Called when validation completes |
| `onError`  | `(error: string) => void` | ❌       | Called when an error occurs      |

## Configuration

`CurpValidationConfig` extends `FlowModuleConfig['CURP_VALIDATION']` with two manager-level options:

```typescript
type CurpValidationConfig = FlowModuleConfig['CURP_VALIDATION'] & {
  maxRetries?: number; // Maximum validation retries before auto-advancing (default: 1)
  prefillFromOcr?: boolean; // Attempt OCR pre-fill on load (default: true)
};
```

| Option           | Type      | Required | Description                                                                    |
| ---------------- | --------- | -------- | ------------------------------------------------------------------------------ |
| `maxRetries`     | `number`  | ❌       | Auto-advance after this many failed validation attempts. Default `1`.          |
| `prefillFromOcr` | `boolean` | ❌       | Pre-fill the CURP field from prior ID OCR data when available. Default `true`. |

`FlowModuleConfig['CURP_VALIDATION']` contributes two more. Both are set on the module's dashboard configuration and arrive through the orchestrator, so consumer code passes them through rather than setting them:

| Option                       | Type      | Description                                                                                     |
| ---------------------------- | --------- | ----------------------------------------------------------------------------------------------- |
| `curpDataMatch`              | `boolean` | Check the CURP against the personal data already collected in the session, not just its format. |
| `deceasedStatusVerification` | `boolean` | Include the registry deceased-status check in validation. The server result determines how the module proceeds. |

## State machine

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

| Status          | Description                                                                       |
| --------------- | --------------------------------------------------------------------------------- |
| `idle`          | Initial state.                                                                    |
| `loading`       | Loading prior OCR data (when `prefillFromOcr` is `true`).                         |
| `enterCurp`     | User enters their CURP.                                                           |
| `verifying`     | Backend verifying the entered CURP.                                               |
| `confirmCurp` | User confirms a successfully generated CURP before verification. |
| `generateCurp`  | No CURP available; user fills the generate form (name, DOB, gender, birth state). |
| `generating`    | Backend generating a CURP from the form.                                          |
| `generateError` | Generate failed; user can retry.                                                  |
| `success` | CURP validated; automatically proceeds to `finished` after 3 seconds. |
| `failure`       | Validation failed (deceased status, mismatch, etc.).                              |
| `finished`      | Terminal.                                                                         |
| `closed`        | User dismissed.                                                                   |

### State properties

| Status | Properties | Meaning |
| --- | --- | --- |
| `enterCurp` | `curp: string`, `isValid: boolean`, `validationErrors?: CurpValidationErrors` | Current input and displayed validation errors. |
| `generateCurp` | `form: GenerateCurpForm`, `isValid: boolean`, `validationErrors?: CurpValidationErrors` | Current generation form and displayed validation errors. |
| `confirmCurp` | `curp: string` | Generated CURP to confirm. |
| `failure` | `retriesLeft: number`, `fromAutoVerify: boolean` | Remaining retries and whether the failed verification began automatically from OCR. |
| `generateError` | `retriesLeft: number` | Remaining generation retries. |

`GenerateCurpForm` has string fields `name`, `firstLastName`, `secondLastName`, `birthDate` (`YYYY-MM-DD`), and `birthState` (two-letter code), plus `gender: 'H' | 'M' | 'X' | ''`. `CurpValidationErrors` maps field names to translation-key strings. `isValid` is optimistic: it means no errors are currently displayed, not that a full validation has passed. Validate on blur with `validateField()`; submission validates the full form.

When OCR provides a CURP, loading proceeds directly to `verifying`; it does not enter `confirmCurp`. Without a usable OCR value, the user enters a CURP. Exhausted `failure` and `generateError` states automatically proceed to `finished` after 3 seconds; completion does not imply successful validation.

## API methods

The module has two input paths — verify an existing CURP, or generate one — and a separate setter for each.

| Method                  | Purpose                                                                        | Callable when                   |
| ----------------------- | ------------------------------------------------------------------------------ | ------------------------------- |
| `load()`                | Start the flow, pulling prior OCR data when `prefillFromOcr` is enabled.       | `idle`                          |
| `setCurp(curp)` | Set the CURP the user is typing. | `enterCurp` |
| `validateField(field)`  | Validate one field on blur. Takes `'curp'` or a key of the generate form.      | `enterCurp`, `generateCurp`     |
| `verify()` | Validate and submit the entered CURP. | `enterCurp` |
| `switchToGenerate()`    | Move to the generate path when the user has no CURP to enter.                  | `enterCurp`                     |
| `setGenerateForm(form)` | Update the generate form. Takes a partial, so you can set one field at a time. | `generateCurp`                  |
| `generate()`            | Submit the generate form.                                                      | `generateCurp`                  |
| `confirmGenerated()` | Submit the generated CURP for verification. | `confirmCurp` |
| `retry()` | Return to the relevant input form. | `failure` or `generateError`, with `retriesLeft > 0` |
| `close()`               | Dismiss the module.                                                            | any non-terminal state          |

Plus the universal lifecycle: `subscribe`, `getState`, `stop`.

## See also

- [Module Patterns → form-based](/sdk-reference/web-sdk-2-module-patterns/#1-form-based-modules)
- [Module: ID OCR](/sdk-reference/web-sdk-2-module-id-ocr/): provides the OCR data this module pre-fills from
- [Individual Modules](/sdk-reference/web-sdk-2-individual-modules/)