Response fields

Choose the standard or extended response and use literal fields with review warnings.

Use the default standard profile for a compact reading, or send profile=extended when your form needs separate name, address or document details. Both preserve the printed values and require review.

Profile	Data returned	Typical use
`standard` (default)	Eight scalar fields plus `mrz`.	Prefill the name, full address and main identifiers.
`extended`	The same eight fields, twelve additional printed scalar fields, `mrz`, and address components on new readings.	Prefill separate form inputs and inspect source information and checks.

The extra address object is a deterministic interpretation of existing OCR text, not twelve more model-extracted fields. It does not add an inference call. See extended extraction and address components.

Fields shared by both profiles

Scalar values are strings or null; keep identifiers as strings to preserve leading zeros. The default response contains exactly these nine data keys.

Field	Type	Meaning
`full_name`	`string` or `null`	Printed name in the document's order.
`curp`	`string` or `null`	CURP as read.
`address`	`string` or `null`	Printed address, if visible.
`date_of_birth`	`string` or `null`	Printed date of birth; do not assume an ISO date format.
`validity`	`string` or `null`	Printed validity year or range, such as `2026-2036`.
`elector_key`	`string` or `null`	Printed elector key.
`cic`	`string` or `null`	Value explicitly labelled CIC outside the MRZ, if readable.
`ocr`	`string` or `null`	Value explicitly labelled OCR outside the MRZ; not a transcript of all text.
`mrz`	Three strings or `null`	The three machine-readable-zone lines, when returned without a conflict.

Field names and error messages are English. Names, addresses and other document values are not translated. Do not complete short identifiers, derive missing fields from MRZ, or convert validity into an exact expiry date without a separate, reviewed process.

Additional printed fields in the extended profile

Fields	How to use them
`given_names`, `paternal_surname`, `maternal_surname`	Separate name inputs when their printed roles are unambiguous. Do not split a one-line full name by counting words.
`sex`	The printed marker, kept as text.
`section`	The electoral section, including leading zeros.
`registration_year`, `issue_year`	Separately labelled printed years; neither replaces `validity`.
`street`	The complete printed street line, including visible number or unit information.
`neighborhood`, `municipality`, `state`, `postal_code`	Visible address details; no postal lookup or geographic completion.

For example, a fictional street value of CALLE EJEMPLO NO 012 EDIF B INT 04 stays intact. A new extended reading can separately expose the literal street name, exterior number, building and interior number under data.address_parts. Display those values for review, retaining data.address as the full original address. Numbers such as 012 and 04 remain strings. Follow the component and source example rather than parsing the address independently in every client.

The extended response also includes sources, checks and quality. Checks are separate from literal values; they do not repair identifiers or establish authenticity. Older saved extended results can lack the new address-component objects.

Standard success envelope

This illustrative standard result uses a fictional name and address. Empty fields remain explicit null values.

{
  "request_id": "00000000-0000-4000-8000-000000000001",
  "status": "succeeded",
  "needs_review": true,
  "data": {
    "full_name": "PERSONA DE EJEMPLO",
    "curp": null,
    "address": "CALLE EJEMPLO NO 012 EDIF B INT 04",
    "date_of_birth": null,
    "validity": null,
    "elector_key": null,
    "cic": null,
    "ocr": null,
    "mrz": null
  },
  "warnings": [
    { "code": "model_confidence_unavailable" },
    { "code": "authenticity_not_verified" },
    { "code": "missing_or_unreadable", "field": "curp" },
    { "code": "missing_or_unreadable", "field": "date_of_birth" },
    { "code": "missing_or_unreadable", "field": "validity" },
    { "code": "missing_or_unreadable", "field": "elector_key" },
    { "code": "missing_or_unreadable", "field": "cic" },
    { "code": "missing_or_unreadable", "field": "ocr" }
  ],
  "expires_at": "2026-09-30T00:00:00.000Z"
}

needs_review is always true. HTTP 200 means a reading was produced; it does not mean every field is present or correct. There is no calibrated confidence percentage in this contract. MRZ, CIC and OCR identifiers need particular care; commercial accuracy for them has not been established.

Warnings

Warnings have a code and may have a field using the English field name. New address warnings use a path such as address_parts.number; see address components.

Code	Interpretation
`authenticity_not_verified`	OCR does not verify authenticity or identity.
`model_confidence_unavailable`	A calibrated model confidence score is unavailable.
`missing_or_unreadable`	The scalar field has no usable reading. Absence and illegibility are not distinguished.
`conflicting_values`	Readings disagree; the scalar value is returned as `null`.
`unexpected_format`	The standard reading has an unusual CURP or elector-key format. Extended readings expose separate format checks. Values are not silently repaired.
`front_contains_mrz_check_sides`	An MRZ was read from the submitted front; review side assignment.
`mrz_requires_review`	Returned MRZ lines require review.
`conflicting_mrz`	MRZ readings disagree; `mrz` is returned as `null`.

Handle unknown warning codes gracefully. Missing warnings are not evidence that a value has been independently verified. A null address can reflect a document that omits the address, poor image quality or a conflict; inspect the document and relevant warnings.