API Reference

Read a voter ID from photos or a PDF

Upload photos or a scanned PDF of a voter ID and get the data printed on it, checks on whether that data agrees, and optionally INE's and RENAPO's answers.

POST /v1/ine/card

Upload photos or a scanned PDF of a voter ID (credencial para votar) and get back the data printed on it, a set of checks on whether that data agrees with itself, and, if you ask for it, INE's own answer on whether the credential is registered and current and RENAPO's record for its CURP. Takes 2 to 4 seconds for photos and costs 10 credits, plus 10 when you ask INE and 5 when you ask RENAPO, each charged only if it answers.

Use it so people photograph their credential instead of typing it, and to catch a card whose front, back, CURP, and elector key do not tell the same story. Works with models E through J, the ones still valid.

What it can and cannot tell you

The checks compare data: the printed front against the machine-readable lines on the back, the back's check digits and QR code against its own numbers, the CURP and elector key against the printed birth date and sex, and the expiry year against today. With verify, the card's identifiers are sent to INE's Lista Nominal service and INE's record is compared with what the card prints. With verify_curp, the same is done with RENAPO for the CURP. Those registry checks are the ones careful printing cannot pass.

A photo cannot prove the plastic is genuine. Holograms, colour-shifting inks, and UV features need the card in hand, and this endpoint does not judge them. Treat consistent: true as "the data is coherent", not as "the card is authentic".

A PDF tells you less still about who is sending it. It is a copy, and anyone the person ever sent it to can upload it again. The response's source field says which one you received, so you can ask more of a PDF: verify and verify_curp to confirm the data with the registries, and a liveness check or a hosted session when you need the person themselves.

Request

Send multipart/form-data, the way a browser form sends files. JSON bodies are not accepted on this endpoint.

Field Type Required Description
front file One of the two Photo or scan of the front of the credential: JPEG, PNG, WebP, or PDF. Gives the printed data and whether the card carries a portrait. Needed for verify_curp.
back file One of the two Photo or scan of the back: JPEG, PNG, WebP, or PDF. Gives the CIC and citizen identifier from the machine-readable lines, and the QR code. Needed for verify and for the front-against-back checks.
verify boolean No Send true to also ask INE about the credential, as /v1/ine/verify does. Adds 4 to 15 seconds and 10 credits, charged only when INE answers.
verify_curp boolean No Send true to also ask RENAPO about the CURP printed on the front, as /v1/curp/lookup does. Adds about 2 seconds and 5 credits, charged only when RENAPO answers. A CURP that fails its own check digit is not sent.
webhook_url string No When provided, the API returns 202 immediately and POSTs the result to this URL once it is ready. http or https only. Redirects are not followed. Max 2048 chars.

Send both sides when you can: most checks need both. Photos should be in focus and show the whole card; one taken sideways or upside down is still read. HEIC photos are not read; convert them to JPEG first. Uploads can be up to 50 MB in total.

A scanned PDF is read too, in the layouts people produce: both sides on one page, one side per page in either order, or one file per side. Each side is looked for on every page, so a single PDF with both sides can go in either field. A voter ID's PDF has one or two pages; a longer one is refused. Reading a PDF takes 3 to 5 seconds.

Example request

curl bash
curl -X POST https://inecheck.com/v1/ine/card \
  -H "x-api-key: rfc_your_api_key" \
  -F [email protected] \
  -F [email protected] \
  -F verify=true \
  -F verify_curp=true

Response (200)

The example uses specimen-style data, modelled on INE's published specimen credential, read without verify or verify_curp. With verify, ine carries the same body /v1/ine/verify returns; with verify_curp, renapo carries the body /v1/curp/lookup returns.

200 OK json
{
  "read": true,
  "source": "photo",
  "consistent": true,
  "message": "The credential was read and its data agrees.",
  "credential": {
    "nombre": "GOMEZ VELAZQUEZ MARGARITA",
    "domicilio": "VIADUCTO TLALPAN NO. 100 COL. ARENAL TEPEPAN, ALCALDIA TLALPAN. C.P. 14610, CIUDAD DE MEXICO.",
    "clave_elector": "GMVLMR80070501M100",
    "curp": "GOVM800705MDFMLR06",
    "fecha_nacimiento": "1980-07-05",
    "sexo": "M",
    "seccion": "0001",
    "anio_registro": 2008,
    "numero_emision": "01",
    "anio_emision": 2019,
    "vigencia": 2029,
    "cic": "183657717",
    "ocr": "0001011111110",
    "id_ciudadano": "011111110"
  },
  "checks": {
    "name_matches_back": true,
    "birth_date_matches_back": true,
    "sex_matches_back": true,
    "vigencia_matches_back": true,
    "seccion_matches_back": true,
    "emision_matches_back": true,
    "mrz_check_digits": true,
    "qr_matches_back": true,
    "curp_check_digit": true,
    "curp_matches_data": true,
    "clave_elector_matches_data": true,
    "not_expired": true,
    "registered_with_ine": null,
    "ine_record_matches_card": null,
    "registered_with_renapo": null,
    "renapo_record_matches_card": null
  },
  "photo": true,
  "mrz": [
    "IDMEX1836577177<<0001011111110",
    "8007050M2912316MEX<01<<12345<0",
    "GOMEZ<VELAZQUEZ<<MARGARITA<<<<"
  ],
  "qr": "http://qr.ine.mx/000101111111001183657717/20191216/P/003660",
  "ine": null,
  "renapo": null
}

read is true (the photos gave credential data), false (nothing on them could be read as a credential: too blurry, cropped, or not a credential), or null (the reader was unavailable, retry later). Only read: true is charged.

Reading the response

  • credential: what the photos say. The printed fields come from the front; cic, ocr, and id_ciudadano come from the back. A field the photos did not give is null. When the name's letters agree with the back, nombre takes its word spacing from the back, which separates each word.
  • checks: each check is true, false, or null when the photos did not give both sides of the comparison.
  • source: photo or pdf: what was uploaded. A PDF is a copy that anyone who was ever sent it can upload again, so it says less than a photo about who holds the card. For PDFs, rely on verify and verify_curp.
  • consistent: false when any check failed, true when at least one ran and none failed, null when none could run. A failed check can also be a misread character on a poor photo, so ask for a retake before you turn someone away.
  • photo: whether a face was found on the front. null when no front was sent.
  • mrz: the three machine-readable lines of the back, as read.
  • qr: the address in the small service QR code on the back. The two dense QR codes are encrypted for INE's own app and are not decoded.
  • ine: INE's answer when verify was sent and the back gave the identifiers, otherwise null. If INE could not be reached, ine.found is null and only the 10 credits for the read are charged.
  • renapo: RENAPO's answer when verify_curp was sent and the front gave a CURP with a valid check digit, otherwise null. If RENAPO could not be reached, renapo.found is null and that lookup is not charged.

The checks

Check Passes when
name_matches_back the name printed on the front is the name in the back's third line.
birth_date_matches_back the front's birth date is the one in the back's second line.
sex_matches_back the front's sex (H or M) is the one on the back. Not evaluated when the front prints a self-perceived gender (X, NB).
vigencia_matches_back the front's expiry year is the one on the back.
seccion_matches_back the electoral section printed on the front is the first four digits of the back's OCR number.
emision_matches_back the front's issue number is the one in the back's second line.
mrz_check_digits the back's four check digits (ICAO 9303) are right: after the CIC, after each date, and over both lines.
qr_matches_back the address in the service QR code is built from the back's OCR number, issue number, and CIC.
curp_check_digit the CURP's last digit is the one its other 17 characters produce.
curp_matches_data the birth date and sex inside the CURP are the printed ones.
clave_elector_matches_data the birth date and sex inside the elector key are the printed ones.
not_expired the expiry year is this year or later. A credential is valid through December 31.
registered_with_ine with verify: INE has a record for the card's identifiers and does not report it as no longer valid.
ine_record_matches_card with verify: the elector key, registration year, issue number, and validity INE has on record are the ones printed on the card.
registered_with_renapo with verify_curp: RENAPO has a record for the card's CURP.
renapo_record_matches_card with verify_curp: the full name, birth date, and sex RENAPO has for that CURP are the ones printed on the card.

Privacy

The photos are read in memory on our own servers and deleted when the request ends. Nothing is stored and no third party receives them. With verify, only the CIC and citizen identifier are sent to INE; with verify_curp, only the CURP is sent to RENAPO. Collecting the person's consent to process their credential is your responsibility.

Webhook mode

Send webhook_url as one more form field and the API answers 202 at once, then POSTs the result to your URL when the read is done. It is most useful with verify, when INE's lookup takes 4 to 15 seconds. See Webhooks for delivery semantics.

curl (webhook) bash
curl -X POST https://inecheck.com/v1/ine/card \
  -H "x-api-key: rfc_your_api_key" \
  -F [email protected] \
  -F [email protected] \
  -F verify=true \
  -F webhook_url=https://example.com/webhooks/ine-card
202 Accepted json
{
  "status": "processing",
  "message": "Card reading in progress"
}
POST to your webhook_url json
{
  "status": 200,
  "body": {
    "read": true,
    "consistent": true,
    "...": "the same body the endpoint returns without webhook_url"
  }
}

In webhook mode the request is charged when it is accepted, including every lookup you asked for (verify, verify_curp), whether or not that registry answers. It is refunded in full when the result is one the direct call would not have charged: read false or null, or a request that could not be used.

Hosted capture

Want us to host the capture? A verification session gives you a link where the person photographs both sides with their phone's live camera and then records the liveness video, and returns this endpoint's response inside its result.

Errors

  • 422 invalid_fields: fields lists what to fix: neither front nor back was sent, or one was sent as text instead of a file. Not charged.
  • 422 unreadable_image: a file could not be opened as an image or a PDF (HEIC, a password-protected PDF, a truncated upload). Not charged.
  • 422 too_many_pages: a PDF has more than 2 pages, so it is not a voter ID. Not charged.
  • 422 invalid_webhook_url: webhook_url is not an address we can call: not http or https, too long, or one that resolves to a private network. Nothing is read. Not charged.