API Reference

# Hosted voter ID verification

Create a link that walks a person through photographing their voter ID and recording a liveness video on their phone, and get one result back.

POST

`/v1/ine/sessions`

Create a verification session and get back a link. The person opens it on their phone and our page walks them through photographing their voter ID and recording a short video of their face. You get one result: the data on the card, the checks on it, and whether the person is live and is the cardholder.

It is /v1/ine/card plus a liveness check and face match, with the capture hosted by us: no app to install, no camera code to write, and nothing for you to upload. A session costs 30 credits.

[Video]

## How it works

1. You create a session with this endpoint and receive its url. Send it to the person by SMS, WhatsApp, or email, show it as a QR code, or open it in a web view or a redirect.
2. The person opens the link in Safari or Chrome on their phone and allows the camera. The page only runs on a phone or tablet: opened on a computer, it shows the link's QR code and asks the person to continue on their phone, unless you sent allow_desktop. They photograph the front of the credential, then the back. Each photo is checked on the spot and taken again if it cannot be read.
3. They record a short video of their face inside a circle, the way a phone sets up face unlock: the page asks for a head turn, a ring around the face fills as they turn, and the next instruction comes once the turn has been seen. The turns are a new random challenge for every recording, and the person gets up to three recordings.
4. The recording ends with about five seconds of holding still. The page asks the camera to zoom in for a moment, where the camera can, and then lights the screen in four colours, in a random order chosen for that recording and at under three changes a second. Both are looked for in the video afterwards; see the capture checks below.
5. The result is posted to your webhook and can be read with GET for 15 minutes. The page shows a closing screen, with a Continue button to your redirect_url if you gave one.

Everything is captured with the live camera. Nothing can be chosen from the phone's gallery, so a photo of someone else's card saved earlier, or a video recorded in advance, cannot be submitted.

## Request body

JSON. Every field is optional; an empty body creates a session with the defaults.


| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `verify` | boolean | No | Send true to also ask INE about the credential, as /v1/ine/verify does. Adds 10 credits and 4 to 15 seconds at the end. |
| `verify_curp` | boolean | No | Send true to also ask RENAPO about the card's CURP, as /v1/curp/lookup does. Adds 5 credits and about 2 seconds. |
| `allow_desktop` | boolean | No | Send true to let the page also run with a computer's webcam. By default it only runs on a phone or tablet, and a computer is shown the link's QR code to continue on a phone. |
| `webhook_url` | string | Recommended | Where the result is posted when the person finishes. Must be a public http or https address. |
| `redirect_url` | string | No | Where the Continue button on the closing screen takes the person. session_id is added to its query string. |
| `reference` | string | No | Your own label for the session, up to 200 bytes: an order or user id. It comes back on the session. Do not put personal data in it; it is the one thing about the session we keep as you sent it. |
| `locale` | string | No | The language of the hosted page: es_MX (the default; es also works) or en. |
| `expires_in` | integer | No | How long the link works, in seconds: 60 to 259200 (three days). The default is 3600, one hour. |


## Example request

curl

```bash
curl -X POST https://inecheck.com/v1/ine/sessions \
  -H "x-api-key: rfc_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "verify": true,
    "webhook_url": "https://example.com/webhooks/ine",
    "redirect_url": "https://example.com/onboarding/done",
    "reference": "order-42"
  }'
```

## Response (201)

201 Created

```json
{
  "id": "ines_H_n67vkCEhvcEfPZ",
  "status": "pending",
  "reference": "order-42",
  "expires_at": "2026-11-12T05:39:01Z",
  "completed_at": null,
  "result": null,
  "url": "https://inecheck.com/verify/2bRlbq2oaymofQ8RmtcJ63OsJrq1szdzp35JyzxDivM",
  "qr_url": "https://inecheck.com/verify/2bRlbq2oaymofQ8RmtcJ63OsJrq1szdzp35JyzxDivM/qr.svg"
}
```

url is the link for the person. It is only returned here, so keep it if you need to send it again. Whoever holds the link can complete the session: send it to the person it is meant for.

qr_url is the same link as a QR code, an SVG image you can put straight into an img tag. Show it when the person starts on a computer, so they scan it and continue on their phone. The hosted page shows the same code by itself when it is opened on a wide screen.

## The result

When the person finishes, the session's status becomes completed and result carries four things. The example uses specimen-style data, modelled on INE's published specimen credential.

result

```json
{
  "verified": true,
  "card": {
    "read": true,
    "source": "photo",
    "consistent": true,
    "message": "The credential was read and its data agrees.",
    "credential": {
      "nombre": "GOMEZ VELAZQUEZ MARGARITA",
      "clave_elector": "GMVLMR80070501M100",
      "curp": "GOVM800705MDFMLR06",
      "cic": "183657717",
      "id_ciudadano": "011111110"
    },
    "checks": {
      "name_matches_back": true,
      "mrz_check_digits": true,
      "registered_with_ine": true,
      "ine_record_matches_card": true
    },
    "ine": {"cic": "183657717", "found": true, "status": "vigente"}
  },
  "liveness": {
    "live": true,
    "match": true,
    "liveness_score": 0.997,
    "similarity": 0.612,
    "continuous": true,
    "challenge": {
      "actions": ["left", "right", "left"],
      "observed": ["left", "right", "left"],
      "passed": true
    },
    "message": "A live person who matches the credential photo."
  },
  "capture": {
    "on_phone": true,
    "camera_genuine": true,
    "flash_followed": true,
    "camera_responded": true
  }
}
```

- `verified`: the one-line answer. true when card.consistent is true (which includes the INE and RENAPO checks you asked for), liveness.live is true, liveness.match is true, and none of the capture checks camera_genuine, flash_followed, and camera_responded is false. false otherwise.
- `card`: the full response of [/v1/ine/card](/docs/endpoints/ine-card), abridged in the example: every credential field, every check, and the ine and renapo answers.
- `liveness`: the checks on the person's last recording, with message saying in one line what they found:
    - `live`: true when the face looks like a person rather than a photo or a screen, the video shows one person throughout, it is not cut together from clips, and the challenge, if sent, was passed. message says which of these failed.
    - `match`: true when the face in the video is the one on the credential. It is reported even when live is false.
    - `liveness_score`: 0 to 1, the median over the frames where the person faces the camera. live needs 0.5 or more. Require a higher score if you prefer to turn away more real people than let a spoof through.
    - `similarity`: -1 to 1. match needs 0.363 or more. A credential's portrait is small and often years old, so real matches sit lower than two selfies of the same person would.
    - `continuous`: true, false, or null. false when the picture jumps from one frame to the next the way two separate clips joined together do: the background shifts in a single step, or the head is suddenly somewhere else. It makes live false. null when the video is too short to tell.
    - `challenge`: the head turns the page asked for (actions), the turns seen in the video (observed), and whether they are the same, in the same order (passed).
- `capture`: four checks on how that recording was captured, described below.

verified: false is not a verdict of fraud. A person who could not make the head turns in three recordings, a worn card whose data was misread, a face in very bright surroundings that the screen's colours did not reach, or INE being unreachable all give false. Read card.checks, liveness, and capture to see which, and decide whether to send a new link.

### The capture checks

capture is about the video itself: was it recorded by a camera in front of this screen, or fed to the page in its place, as a virtual camera playing a recording does? Each check is true, false, or null when it could not be made. A recording that fails one is taken again like one that fails the head turns, up to three recordings in all; the last one stands.


| Check | true when |
| --- | --- |
| `on_phone` | the browser reports a phone or tablet. For your information only: it does not affect verified, and it is false on a session you created with allow_desktop that was done on a computer. |
| `camera_genuine` | the camera's name is not that of a known virtual-camera program, and the browser is not being driven by automation. null when the camera reports no name. |
| `flash_followed` | the face in the video took on the colours the screen showed, in the order the server chose for that recording. A video that was not lit by this screen does not follow a sequence made up a moment before. |
| `camera_responded` | the picture grew when the camera was asked to zoom in. null on a camera that cannot zoom from a web page, such as an iPhone's in Safari; there is then nothing to ask of it. |


## Receiving the result

### By webhook

If the session has a webhook_url, the session with its result is posted to it once, when the person finishes, in the same envelope as the other webhooks:

POST to your webhook_url

```json
{
  "status": 200,
  "body": {
    "id": "ines_H_n67vkCEhvcEfPZ",
    "status": "completed",
    "reference": "order-42",
    "expires_at": "2026-11-12T05:39:01Z",
    "completed_at": "2026-11-12T04:52:17Z",
    "result": {"verified": true, "card": {}, "liveness": {}, "capture": {}}
  }
}
```

Answer with a 2xx. Delivery is not retried; see [Webhooks](/docs/webhooks) for the addresses that are accepted. The webhook is the durable delivery: the result is not stored on our side.

The webhook is signed. Check its signature before you accept a person as verified, or anyone who learns your webhook URL could post a result of their own. [Verify the signature](/docs/webhooks#signatures)

### By reading the session

GET

`/v1/ine/sessions/:id`

curl

```bash
curl https://inecheck.com/v1/ine/sessions/ines_H_n67vkCEhvcEfPZ \
  -H "x-api-key: rfc_your_api_key"
```

Free. Returns the same session object. result is filled for 15 minutes after the person finishes, while it is held in memory; after that the status and timestamps still come back, with result: null. Use it to poll while the person is on the page, or when the redirect brings them back with session_id.

## Statuses

- `pending`: the link has not been completed yet. The person may not have opened it, or may be on the page.
- `completed`: the person finished and the result was produced. A session completes once; the link stops working.
- `expired`: expires_at passed without the session being completed. Its credits were refunded. Create a new session to try again.

## Pricing

30 credits: a card read and a liveness check. verify adds 10 and verify_curp adds 5. The session is charged when it is created and refunded in full if it expires without being completed, so a link nobody opens costs nothing.

Unlike /v1/ine/card, the verify and verify_curp credits are part of the session's price whether or not INE or RENAPO answered. If a registry was unreachable, card.ine.found or card.renapo.found is null and the matching checks are null.

## What it can and cannot tell you

The live camera and the random head turns stop the common attacks: a photo of a card that is not in the person's hands, a printed photo or a screen held up to the camera, a video recorded earlier. The card's data is checked against itself and, when you ask, against INE and RENAPO.

The capture checks are aimed at video fed to the page in place of a camera, such as a virtual camera playing a recording: such a video did not hear the request to zoom and was not lit by this screen. liveness.continuous adds a check that the video is one recording and not separate clips joined together; it sees a hard cut, not clips blended into each other over several frames.

These checks run in the other person's browser, where a determined attacker controls what is reported, so they raise the cost of an attack; they do not prove anything. The flash check needs the screen to be a noticeable light on the face: very bright surroundings can make it fail, and the page then asks for another recording. Its threshold is provisional, set on simulated video and still to be confirmed on a range of phones. A face swapped in live that is re-lit correctly is not caught.

It is not a certified presentation-attack or injection-attack detection product, and a photo cannot prove the plastic is genuine: holograms and security inks need the card in hand. Use it alongside your own risk controls.

## Privacy

The photos and the video are processed in memory on our own servers while the person is on the page and are not stored; 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. We keep the session's options, status, and timestamps, and your reference. Collecting the person's consent to process their credential and their image is your responsibility, before you send them the link.

## Limits

- The page needs a phone or tablet browser with camera access: Safari on iOS, Chrome on Android. A computer is only let through with allow_desktop. Browsers inside other apps (a link opened within a chat or social app) may block the camera; the page tells the person to open the link in Safari or Chrome.
- Credential models E through J are read. If the connection drops while the person is on the page, the steps start over.
- Sessions are created with an API key on /v1. They are not available through the RapidAPI listing.

## Errors

- `422 invalid_fields`: fields lists what to fix: a webhook_url that is not a public address, a redirect_url that is not http or https, an unknown locale, an expires_in out of range, a reference that is too long, or a verify or allow_desktop flag that is not a boolean. Not charged.
- `404 not_found`: on GET, no session with that id belongs to the account of the API key.