# CURP Validation Module Guide

This guide is specific to Web SDK 2.0. If you are still using 1.x, you can find documentation [here](https://developer.incode.com/docs/web-sdk-reference). Contact your Incode Representative for upgrade information and check if you are a candidate for this upgrade.

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.

Follows the [form-based pattern](https://developer.incode.com/docs/web-sdk-2-module-patterns#1-form-based-modules) with three input variants (enter, confirm, generate). See the patterns page for the shared lifecycle.

## 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`. |

Plus the dashboard-driven fields from `FlowModuleConfig['CURP_VALIDATION']`.

## 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` | Backend returned an OCR'd CURP candidate; user confirms or rejects. |
| `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. |
| `failure` | Validation failed (deceased status, mismatch, etc.). |
| `finished` | Terminal. |
| `closed` | User dismissed. |