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

This module follows the form-based pattern 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.

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:

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.