Extended extraction
Opt in to printed fields, separated address components, provenance and review checks.
On this page
The default response stays compact: eight scalar fields and raw MRZ. Add profile=extended to /api/v3/ine to request the expanded schema. This profile is a beta with evaluation in progress. Twenty supported fields does not mean twenty readable fields on every credential or 100% accuracy.
Read the measured results and remaining limitations before deciding how to use this profile.
curl https://ocr.ecostudios.dev/api/v3/ine \
-H "X-API-Key: $INE_API_KEY" \
-H 'Idempotency-Key: your-unique-transaction-id' \
-F 'profile=extended' \
-F 'front=@front.jpg' \
-F 'back=@back.webp'
Printed fields
| Group | Fields | Where to look on the INE |
|---|---|---|
| Name | full_name, given_names, paternal_surname, maternal_surname | The holder's NOMBRE block; separate names require identifiable printed roles. |
| Holder | curp, date_of_birth, sex | CURP, FECHA DE NACIMIENTO and SEXO. |
| Address | address, street, neighborhood, municipality, state, postal_code | The visible DOMICILIO block, not codes elsewhere on the card. |
| Electoral | elector_key, section, registration_year | CLAVE DE ELECTOR, SECCIÓN and AÑO DE REGISTRO. |
| Document | issue_year, validity, cic, ocr | EMISIÓN, VIGENCIA, and explicitly identified CIC / OCR outside MRZ. Availability varies by credential. |
Use the field-by-field reference for exact meanings. In particular, section is an electoral section, while address_parts.block means an address manzana. issue_year is an issuance year, not an issue-count number.
All 20 printed scalar values are strings or null. data.mrz preserves the three raw lines when available. Leading zeroes are meaningful; never convert identifiers to numbers. Address components are extracted only when visibly supported; they are not enriched from an external address service. Names are not guessed by splitting a single text string. Unavailable, unreadable or conflicting values remain null.
Response metadata
| Property | Meaning |
|---|---|
profile | extended, identifying the selected API output profile. |
sources.FIELD | Observed input side (front / back) and region (name_block, address_block or printed_label) for a printed field. It is not a measured image bounding box. |
sources.address_parts.PART | Exact text offsets used by the deterministic parser; see source tracing. This is different from the model's region observations. |
checks | Separate format, checksum and consistency results. These do not overwrite the literal data values. |
quality | Unvalidated observations about each supplied image, such as suspected glare. Not a confidence percentage or authenticity verdict. |
needs_review | Always true, even when individual checks pass. |
Sources show how the output was obtained; they do not prove it matches the original card. See the shared envelope properties for request_id, status, warnings and expires_at.
Separated address components
New extended readings also include data.address_parts and sources.address_parts. A conservative parser separates supported labels in the existing OCR text into twelve nullable values, including street type/name, exterior/interior number, building (edificio), block (manzana) and lot (lote). It makes no additional model call and leaves address, the complete street line and the other twenty-field values unchanged.
For a fictional street CALLE EJEMPLO NO 012 EDIF B INT 04, supported components can expose CALLE, EJEMPLO, 012, B and 04 separately. Each populated component has a source field and exact substring offsets. Ambiguous or conflicting components remain null. This is parsing of OCR output, not address validation or enrichment.
Manzana and lote are optional parts of the printed DOMICILIO, not dedicated electoral fields present on every INE. MZA 003 LT 007, for example, can describe block 003 and lot 007; it says nothing about SECCIÓN. Interior (unit) and building (building) remain separate. See block, lot, unit and building.
The parser result is saved once with a new reading. GET and replay return it as stored; they do not reparse older results, which may omit both objects. Handle that absence when integrating. Read the address component guide for all twelve fields, source offsets and warning codes.
Checks and image observations
Checks evaluate CURP format/check digit, supported date formats, elector-key format, TD1 MRZ structure/check digits, expiry-year interpretation and comparable front/back text. Missing or unsupported data yields a not_checked check rather than a fabricated pass. Printed expiry year is not an official determination of INE validity.
Image observations may flag suspected blur, glare, cropping, rotation, incorrect side or another document. These observations are not calibrated confidence scores and do not establish authenticity. They do not reject photographs on their own. Deterministic file decoding and dimension limits are enforced before reserving a unit.
Follow the field-specific warning codes. A failed checksum flags an inconsistency that may come from an OCR mistake or the document itself. A passed checksum does not prove extraction accuracy, authenticity or the holder's identity.
Single-side reading
Use mode=front with only front, or mode=back with only back. The default mode=both requires both. A single-side request still consumes one reading unit; missing information on the omitted side remains unavailable. Use both sides when your workflow needs the full credential.
The same key must use the same image bytes, profile and mode on replay. Changing an option requires a new transaction. Earlier API versions retain their original input and response contracts.