Mexico - INE Biometric Database Verification

Mexico - INE Biometric Database Verification validates the authenticity of an end-user's identity by comparing their selfie against the biometric portrait held in the Mexican National Electoral Institute (INE) registry. It supports identity verification by validating end-user data and performing a biometric face match against government-held records to provide the highest level of assurance for Mexican identity verification.

The end-user must use their valid Mexican Voter card.

This solution does not return any data from the registry, it returns validation results for data validations and face match results.

Mexico - INE Biometric Database Verification can be can be used in two ways: as an add-on to your identity verification flow or as a standalone check.

As an add-on to your IDV flow

The solution is available via SDK, web and API, and the check runs automatically once your verification flow has captured a supported Voter card and a selfie. No new integration is needed i.e., it uses the same integration that is used for the identity verification.

As a standalone check

The solution is available only via API (there is no end-user flow) and a new integration is required. You are responsible for collecting and sending relevant Voter card data and selfie.

Contact your solutions engineer for info and configuration.

All session-related info is returned via decision webhook and can be polled from different API endpoints. The results of the verification can also be viewed in the Veriff Customer Portal, under the Webhooks tab.

If any data was extracted from the document (for example during the end-user flow), this data is provided in the decision webhook payload and GET /decision endpoint’s response payload.

Prerequisites

• You have an integration set up with Veriff

• The database check is configured for that integration by your Solutions Engineer

• You have registered directly with Instituto Nacional Electoral (Veriff can help facilitate the registration, see below for more info)

• You have configured the decision webhook to get responses from Veriff (see the how-to in webhooks' Set up webhooks section)

• You have collected and are able to send info about end-user’s consent for INE biometric data processing

• If using this as an add-on to an identity verification flow:

  • A successful identity verification session is a prerequisite for this check to run

• If using this as a standalone over API:

  • You are ready to collect and send Veriff your end-user's data and selfie

  • Veriff strongly recommends that you create and send us the endUserId or vendorData

Key terminology

How to register with INE?

Veriff can help facilitate the registration with our third party provider. Contact your Solutions Engineer for help.

After you have registered with the third-party provider, you must share with us one time the following data points:

• Encryption key

• Third party provider’s endpoint URL (Base URL of their API endpoint)

• Institution ID (Institution identifier issued by the third party provider)

• Station ID (Station identifier for the third party provider connection)

• Latitude (Latitude of the station location)

• Longitude (Longitude of the station location)

• Postal code (Postal code of the station location)

• City (City of the station location)

• State (State of the station location, a 2 digit code)

End-user data sources

The "end-user data sources" refer to the origins from where the end-user's information can be collected for the registry check. Mexico - INE Biometric Database Verification uses document data and initData, depending if the solution is an add-on or used as standalone.

The minimum data combination to run a successful check is: CIC (voter card credential identification code) + document country code + document type + end-user consent + selfie image

Document data

When used as an add-on, data is extracted from the end-user's captured Voter card: the CIC, first name, father's last name, mother's last name, document registration year, and document issue year. None of these are required in the POST /sessions payload for an add-on session, they are populated once the document is captured.

InitData

This is data that you provide when creating a verification session, i.e. the parameters you specify in the POST /sessions request.

Regardless of which flow you use, end-user consent for INE biometric data processing must always be sent via the consents array in initData at session creation. Unlike the other fields mentioned in Document data section, consent is not collected inside the identity verification flow itself and does not move to document capture, even in the add-on flow. It must be present in the POST /sessions payload.

Optional fields are matched against the INE registry only when the corresponding validation has been enabled for your integration by your Solutions Engineer. If a validation is not enabled, the field is accepted but has no effect on the verification result and no corresponding entry appears in validations.

See the Available validation_check values table below for which checks require SE enablement.

Parameters that can be sent via initData:

• verification: object Root object containing all session parameters

  • person: object Object containing person information

    • idNumber: string 18-character CURP [OPTIONAL]

    • firstName: string End-user's first name. Matched against INE registry records [OPTIONAL]

    • lastName: string End-user's father's last name (apellido paterno). Matched against INE registry records [OPTIONAL]

    • secondLastName: string End-user's mother's last name (apellido materno). Matched against INE registry records [OPTIONAL]

  • document: object Object containing document information

    • number: string 9-digit CIC from the voter card. Mandatory for the standalone flow; extracted from the document in the add-on flow.

    • country: string Must be MX. Mandatory for the standalone flow; extracted from the document in the add-on flow.

    • type: string Document type, must be ID_CARD. Mandatory for the standalone flow; extracted from the document in the add-on flow.

    • firstIssue: string Document registration date in YYYY-MM-DD format (only the year portion is used for matching) [OPTIONAL]

    • validFrom: string Document issue date in YYYY-MM-DD format (only the year portion is used for matching) [OPTIONAL]

  • consents: array Required array containing the end-user's consent for INE biometric data processing. Must be sent via initData for both add-on and standalone flows [REQUIRED]

    • type: string Must be ine [REQUIRED]

    • approved: boolean Must be true [REQUIRED]

Flow overview

Use as an identity verification add-on

Use this when the check should run automatically as part of your existing identity verification flow. This add-on runs on any session created on an integration where your Solutions Engineer has enabled it, there is no session-level parameter that turns it on or selects it.

1. Create the session, passing the mandatory verification.consents array (type: ine, approved: true). This is the only required input for an add-on session. Unlike the rest of this flow, consent is not collected inside the identity verification flow itself, your identity verification does not present a consent screen for this check, so you must include it at session creation.

Session creation bash example

curl -X POST \
  --url '/v1/sessions/' \
  -H 'X-AUTH-CLIENT: your-api-key' \
  -H 'Content-Type: application/json' \
  -d '{
    "verification": {
        "callback": "https://exampleURL.com",
        "vendorData": "12345678",
        "consents": [
            {
                "type": "ine",
                "approved": true
            }
        ]
    }
}'

2. The end-user submits their document. For this check to run, the end-user must present a valid Mexican Voter card (INE credential).

3. Veriff extracts the required data from it.

4. The end-user captures a selfie.

5. Veriff forwards the identity data extracted from the document, together with the selfie, to the INE registry.

6. The registry returns whether the person was found, the face-match result, and the result of each enabled identity-data match.

7. Check the decision data and/or session-related info from the decision webhook and/or query the data from the {{variable.GET-sessions-decision-link}} endpoint, exactly as in the standalone flow below.

Use as standalone check via API

1. Generate a verification session using the API keys and the baseURL of your integration (see the API Documentation and API Reference how to find these).

   • Make sure to pass the mandatory verification.document.number parameter with the end-user's 9-digit CIC value.

   • Make sure to pass the mandatory verification.document.country parameter with the MX value.

   • Make sure to pass the mandatory verification.document.type parameter with the ID_CARD value.

   • Make sure to pass the mandatory verification.consents array with type: ine and approved: true.

   • Veriff strongly recommends you create and send the endUserId or vendorData.

Session creation example

curl -X POST \
  --url '/v1/sessions/' \
  -H 'X-AUTH-CLIENT: your-api-key' \
  -H 'Content-Type: application/json' \
  -d '{
    "verification": {
        "callback": "https://veriff.com",
        "vendorData": "12345678",
        "endUserId": "a1b2c35d-e8f7-6d5e-3cd2-a1b2c35db3d4",
        "person": {
            "idNumber": "GARJ000000HMCRLP00",
            "firstName": "JUAN",
            "lastName": "GARCIA",
            "secondLastName": "LOPEZ"
        },
        "document": {
            "type": "ID_CARD",
            "number": "000000000",
            "country": "MX",
            "validFrom": "2020-03-10",
            "firstIssue": "2018-06-15"
        },
        "consents": [
            {
                "type": "ine",
                "approved": true
            }
        ]
    }
}'

{
    "verification": {
        "callback": "https://veriff.com",
        "vendorData": "12345678",
        "endUserId": "a1b2c35d-e8f7-6d5e-3cd2-a1b2c35db3d4",
        "person": {
            "idNumber": "GARJ000000HMCRLP00",
            "firstName": "JUAN",
            "lastName": "GARCIA",
            "secondLastName": "LOPEZ"
        },
        "document": {
            "type": "ID_CARD",
            "number": "000000000",
            "country": "MX",
            "validFrom": "2020-03-10",
            "firstIssue": "2018-06-15"
        },
        "consents": [
            {
                "type": "ine",
                "approved": true
            }
        ]
    }
}

2. Upload the end-user's selfie via POST /sessions/{sessionId}/media call. This is matched against the portrait stored in the INE registry.

   • Use your image-capturing method, or send a previously collected selfie image (see the POST /sessions/{sessionId}/media documentation for more info about how to upload image files).

   • This solution supports .jpeg and .png formats.

   • Specify the image.context as face (see Context types (image, video) for more info about image context types).

   • This endpoint requires endpoint level authentication via X-HMAC-SIGNATURE header. See HMAC Authentication and Endpoint Security for general info about signature creation.

Media upload example

curl -X POST \
  --url '/v1/sessions/aea9ba6d-1b47-47fc-a4fc-f72b6d3584a7/media' \
  -H 'X-AUTH-CLIENT: your-api-key' \
  -H 'X-HMAC-SIGNATURE: 034c6da2bb31fd9e6892516c6d7b90ebe10f79b47cfb3d155d77b4d9b66e1d53' \
  -H 'Content-Type: application/json' \
  -d '{
    "image": {
        "context": "face",
        "content": "data:image/jpeg;base64,...",
        "timestamp": "2026-04-01T10:00:00.000Z"
    }
}'

{
    "image": {
        "context": "face",
        "content": "data:image/jpeg;base64,...",
        "timestamp": "2026-04-01T10:00:00.000Z"
    }
}

3. Patch session status to submitted status using PATCH /sessions/{sessionId} call.

   • This endpoint requires endpoint level authentication via X-HMAC-SIGNATURE header. See HMAC Authentication and Endpoint Security for general info about signature creation.

Session update example

curl -X PATCH \
  --url '/v1/sessions/fd5c1563-1d23-4b1a-ae46-7ba429927ed8' \
  -H 'X-AUTH-CLIENT: your-api-key' \
  -H 'X-HMAC-SIGNATURE: 034c6da2bb31fd9e6892516c6d7b90ebe10f79b47cfb3d155d77b4d9b66e1d53' \
  -H 'Content-Type: application/json' \
  -d '{
    "verification": {
        "status": "submitted"
    }
}'

{
    "verification": {
        "status": "submitted"
    }
}

4. Check the decision data and/or session related info from the decision webhook and/or query the data from the GET /sessions/{sessionId}/decision endpoint. Solution-specific overview of what to expect is provided below in the Find decision and/or session related info > Solution-specific parameters section.

Find decision and/or session related info

You can get the data from three sources:

• Receive the decision webhook (full examples with placeholder values below)

• Query the results via GET /sessions/{sessionId}/decision endpoint (payload identical to webhook)

• View the session in Veriff Customer Portal > Webhooks tab

Note that the decision webhook and GET /sessions/{sessionId}/decision API response payloads are identical.

Solution-specific parameters

Info related to INE Biometric Database Verification is returned in the registryValidations.MX_INE object. This object contains the overall registry check result, the individual validation outcomes, and error details when applicable.

Structure of MX_INE object

{
  "MX_INE": {
    "status": "success | failure | error",
    "data": null,
    "validations": { ... } | null,
    "error": { ... } | null,
    "timestamp": "ISO-8601 string" | null
  }
}

Parameters in MX_INE explained

• verification: object Verification results object

• registryValidations: object Registry validation results object

  • MX_INE: object Registry validation result for Mexico - INE Biometric Verification

    • status: string Overall result of the registry check. One of: success, failure, or error. See below for more info.

    • data: null Always null . The INE registry does not return person data, it only confirms or denies matches

    • validations: object | null Map of specific validation check results. null when status is error

      • <validation_check>: object A specific validation check result. See below for available values.

        • result: string Outcome of the validation. One of: success (passed), failure (failed), not_applicable (could not run due to an upstream failure)

        • reason: string | null Machine-readable reason for the result. null on result: success . See below for more info.

    • error: object | null Error details when status is error. null otherwise

      • code: string Machine-readable error code, always registry_error

      • message: string Human-readable error description. One of: registry_unavailable, technical_issues

    • timestamp: string | null ISO-8601 timestamp of when the registry responded. null when the registry was not reached

Possible status values

Available validation_check values

Possible reason values

Possible error.message values

Note about object and field visibility

Some objects and fields within the registryValidations.MX_INE object are optional.

You should expect that any key may be omitted from the payload or return a null value.

A field is included in the response only when:

• The registry check was successfully performed

• The specific validation (e.g., first_name_match) is enabled in your configuration

• The input data required for that specific check was provided

Validations that have been disabled by your Solutions Engineer are not included in the webhook output. Validations that are not_applicable due to a cascade failure are included.

Because the response schema is dynamic and based on both your specific configuration and the quality of the data provided, your application logic must account for omitted keys and null values as a standard part of the verification workflow.

Note on session outcomes

An approved session is identified by a verification.status of approved. For a clean result, all four core validations must pass: consent_obtained, person_registered, selfie_registry_match, and not_reported_lost_or_stolen.

Any enabled optional field validations must also pass or return not_applicable (when the corresponding input was not provided).

If optional field validations are not enabled, they are omitted from the payload and do not impact the approved status.

Validation cascade

The INE registry uses a validation cascade: if a core validation fails, downstream validations are automatically set to not_applicable. Several stages run before the registry is ever contacted (mandatory-input presence, consent, and input format), and any one of them failing skips the registry call entirely. See the cascade order and rules below for the exact propagation.

Cascade order

Session submitted
│
├── A mandatory input (CIC, or an enabled field's own required input) is missing
│     → the missing field validation = FAIL, reason: input_not_provided
│     → consent_obtained, person_registered, selfie_registry_match, not_reported_lost_or_stolen = N/A, reason: input_not_provided
│     → the remaining field validations = N/A, reason: input_not_provided
│     → Registry is not called
│
└── All mandatory inputs present
      │
      └── Consent provided and approved?
            ├─ NO (missing, or approved: false) → consent_obtained = FAIL, reason: input_not_provided or consent_not_obtained
            │       reasonCode: 640
            │       → person_registered, selfie_registry_match, not_reported_lost_or_stolen = N/A, reason: input_not_provided
            │       → all 6 field validations = N/A, reason: input_not_provided
            │       → Registry is not called
            │
            └── YES → consent_obtained = PASS
                     │
                     └── Input format valid (CIC, CURP, name fields)?
                           ├─ NO → person_registered = FAIL, reason: input_not_provided
                           │       → everything else = N/A, reason: input_not_provided
                           │       → Registry is not called
                           │
                           └── YES → Registry contacted
                                     │
                                     ├── Registry error (unavailable, timeout, or invalid response)
                                     │     → status: "error"
                                     │     → validations: null
                                     │
                                     └── Registry responds successfully
                                           │
                                           └── Person found in INE registry?
                                                 ├─ NO → person_registered = FAIL
                                                 │       reasonCode: 902
                                                 │       All remaining validations = N/A
                                                 │
                                                 └─ YES → person_registered = PASS
                                                          │
                                                          └── Face match score ≥ threshold?
                                                                ├─ NO → selfie_registry_match = FAIL
                                                                │       reasonCode: 581
                                                                │       not_reported_lost_or_stolen = N/A
                                                                │       All field validations = N/A
                                                                │
                                                                └─ YES → selfie_registry_match = PASS
                                                                         │
                                                                         └── Document reported lost or stolen?
                                                                               ├─ YES → not_reported_lost_or_stolen = FAIL
                                                                               │        reasonCode: 904
                                                                               │        All field validations = N/A
                                                                               │
                                                                               └─ NO → not_reported_lost_or_stolen = PASS
                                                                                        │
                                                                                        └── Each enabled field validation runs independently
                                                                                              ├─ first_name_match
                                                                                              ├─ father_last_name_match
                                                                                              ├─ mother_last_name_match
                                                                                              ├─ personal_number_match
                                                                                              ├─ registration_year_match
                                                                                              └─ issue_year_match
                                                                                                    FAIL → reasonCode: 903

Cascade rules

1. If a mandatory input is missing (the CIC, or an enabled field validation's own required input), the registry is not called at all.

   1. The specific field validation missing its input returns failure.

   2. consent_obtained, person_registered, selfie_registry_match, and not_reported_lost_or_stolen are set to not_applicable.

   3. Every remaining field validation is set to not_applicable.

   4. All of these carry reason: input_not_provided.

2. If consent is missing entirely, or approved is false, the registry is not called.

   1. consent_obtained fails with reason: input_not_provided (consent info not sent) or consent_not_obtained (approved: false sent).

   2. reasonCode: 640.

   3. Every other validation is set to not_applicable with reason: input_not_provided.

3. If a provided input fails local format validation (an invalid CIC, CURP, or name field), the registry is not called.

   1. person_registered fails with reason: input_not_provided.

   2. Every other validation is set to not_applicable with reason: input_not_provided.

4. If the registry is unavailable:

   1. validations is null and error is populated.

   2. No individual validation results are returned.

5. If person_registered fails because the registry responded that the person was not found, it carries reason: person_not_found, reasonCode: 902. All remaining validations are set to not_applicable with the same reason, person_not_found.

6. If selfie_registry_match fails, it carries reason: selfie_mismatch, reasonCode: 581. All remaining validations are set to not_applicable with the same reason, selfie_mismatch.

7. If not_reported_lost_or_stolen fails, it carries reason: value_mismatch, reasonCode: 904. All field validations are set to not_applicable with the same reason, value_mismatch.

8. If all core validations pass, each enabled field validation is evaluated independently. A failure in one does not block the others. A failure carries reasonCode: 903.

{
  "status": "success",
  "verification": {
    "id": "12df6045-3846-3e45-946a-14fa6136d78b",
    "attemptId": "00bca969-b53a-4fad-b065-874d41a7b2b8",
    "vendorData": "12345678",
    "endUserId": "a1b2c35d-e8f7-6d5e-3cd2-a1b2c35db3d4",
    "status": "declined",
    "code": 9102,
    "reason": "Person not found",
    "reasonCode": 902,
    "decisionTime": "2026-04-01T10:01:05.916Z",
    "acceptanceTime": "2026-04-01T10:00:27.000Z",
    "submissionTime": "2026-04-01T10:01:00.736Z",
    "person": {
      "firstName": "JUAN",
      "lastName": "GARCIA",
      "dateOfBirth": null,
      "gender": null,
      "nationality": null,
      "idNumber": "GARJ000000HMCRLP00",
      "yearOfBirth": null,
      "placeOfBirth": null
    },
    "document": {
      "number": "000000000",
      "type": "ID_CARD",
      "country": "MX",
      "state": null
    },
    "registryValidations": {
      "MX_INE": {
        "status": "failure",
        "data": null,
        "validations": {
          "consent_obtained": {
            "result": "success",
            "reason": null
          },
          "person_registered": {
            "result": "failure",
            "reason": "person_not_found"
          },
          "selfie_registry_match": {
            "result": "not_applicable",
            "reason": "person_not_found"
          },
          "not_reported_lost_or_stolen": {
            "result": "not_applicable",
            "reason": "person_not_found"
          },
          "first_name_match": {
            "result": "not_applicable",
            "reason": "person_not_found"
          },
          "father_last_name_match": {
            "result": "not_applicable",
            "reason": "person_not_found"
          },
          "mother_last_name_match": {
            "result": "not_applicable",
            "reason": "person_not_found"
          },
          "personal_number_match": {
            "result": "not_applicable",
            "reason": "person_not_found"
          },
          "registration_year_match": {
            "result": "not_applicable",
            "reason": "person_not_found"
          },
          "issue_year_match": {
            "result": "not_applicable",
            "reason": "person_not_found"
          }
        },
        "error": null,
        "timestamp": "2026-04-01T10:01:05.000Z"
      }
    },
    "additionalVerifiedData": {}
  },
  "technicalData": {
    "ip": null
  }
}

Sample payload of registryValidations.MX_INE object

The following is a sample response for an approved session with all possible registryValidations.MX_INE object values. All strings and IDs are placeholder values used for illustrative purposes only. Your production payload will contain real-time data from the registry check.

{
  "verification": {
    "registryValidations": {
      "MX_INE": {
        "status": "success",
        "data": null,
        "validations": {
          "consent_obtained": {
            "result": "success",
            "reason": null
          },
          "person_registered": {
            "result": "success",
            "reason": null
          },
          "selfie_registry_match": {
            "result": "success",
            "reason": null
          },
          "not_reported_lost_or_stolen": {
            "result": "success",
            "reason": null
          },
          "first_name_match": {
            "result": "success",
            "reason": null
          },
          "father_last_name_match": {
            "result": "success",
            "reason": null
          },
          "mother_last_name_match": {
            "result": "success",
            "reason": null
          },
          "personal_number_match": {
            "result": "success",
            "reason": null
          },
          "registration_year_match": {
            "result": "success",
            "reason": null
          },
          "issue_year_match": {
            "result": "success",
            "reason": null
          }
        },
        "error": null,
        "timestamp": "2026-04-01T10:01:05.000Z"
      }
    }
  }
}

Webhook payload

The examples below use placeholder data to show all mandatory parameters and possible Mexico - INE Biometric Database Verification fields. While mandatory fields are always present, solution-specific keys are omitted if a feature is disabled or data extraction fails.

Depending on your integration's configuration, your production payload may contain additional parameters; for info on fields from other solutions, see the decision webhook's documentation.

Sample requests

{
  "status": "success",
  "verification": {
    "id": "12df6045-3846-3e45-946a-14fa6136d78b",
    "attemptId": "00bca969-b53a-4fad-b065-874d41a7b2b8",
    "vendorData": "12345678",
    "endUserId": "a1b2c35d-e8f7-6d5e-3cd2-a1b2c35db3d4",
    "status": "approved",
    "code": 9001,
    "reason": null,
    "reasonCode": null,
    "decisionTime": "2026-04-01T10:01:05.916Z",
    "acceptanceTime": "2026-04-01T10:00:27.000Z",
    "submissionTime": "2026-04-01T10:01:00.736Z",
    "person": {
      "firstName": "JUAN",
      "lastName": "GARCIA",
      "dateOfBirth": null,
      "gender": null,
      "nationality": null,
      "idNumber": "GARJ000000HMCRLP00",
      "yearOfBirth": null,
      "placeOfBirth": null
    },
    "document": {
      "number": "000000000",
      "type": "ID_CARD",
      "country": "MX",
      "state": null
    },
    "registryValidations": {
      "MX_INE": {
        "status": "success",
        "data": null,
        "validations": {
          "consent_obtained": {
            "result": "success",
            "reason": null
          },
          "person_registered": {
            "result": "success",
            "reason": null
          },
          "selfie_registry_match": {
            "result": "success",
            "reason": null
          },
          "not_reported_lost_or_stolen": {
            "result": "success",
            "reason": null
          },
          "first_name_match": {
            "result": "success",
            "reason": null
          },
          "father_last_name_match": {
            "result": "success",
            "reason": null
          },
          "mother_last_name_match": {
            "result": "success",
            "reason": null
          },
          "personal_number_match": {
            "result": "success",
            "reason": null
          },
          "registration_year_match": {
            "result": "success",
            "reason": null
          },
          "issue_year_match": {
            "result": "success",
            "reason": null
          }
        },
        "error": null,
        "timestamp": "2026-04-01T10:01:05.000Z"
      }
    },
    "additionalVerifiedData": {}
  },
  "technicalData": {
    "ip": null
  }
}

{
  "status": "success",
  "verification": {
    "id": "12df6045-3846-3e45-946a-14fa6136d78b",
    "attemptId": "00bca969-b53a-4fad-b065-874d41a7b2b8",
    "vendorData": "12345678",
    "endUserId": "a1b2c35d-e8f7-6d5e-3cd2-a1b2c35db3d4",
    "status": "approved",
    "code": 9001,
    "reason": null,
    "reasonCode": null,
    "decisionTime": "2026-04-01T10:01:05.916Z",
    "acceptanceTime": "2026-04-01T10:00:27.000Z",
    "submissionTime": "2026-04-01T10:01:00.736Z",
    "person": {
      "firstName": "JUAN",
      "lastName": null,
      "dateOfBirth": null,
      "gender": null,
      "nationality": null,
      "idNumber": null,
      "yearOfBirth": null,
      "placeOfBirth": null
    },
    "document": {
      "number": "000000000",
      "type": "ID_CARD",
      "country": "MX",
      "state": null
    },
    "registryValidations": {
      "MX_INE": {
        "status": "success",
        "data": null,
        "validations": {
          "consent_obtained": {
            "result": "success",
            "reason": null
          },
          "person_registered": {
            "result": "success",
            "reason": null
          },
          "selfie_registry_match": {
            "result": "success",
            "reason": null
          },
          "not_reported_lost_or_stolen": {
            "result": "success",
            "reason": null
          },
          "first_name_match": {
            "result": "success",
            "reason": null
          },
          "father_last_name_match": {
            "result": "not_applicable",
            "reason": "input_not_provided"
          },
          "personal_number_match": {
            "result": "not_applicable",
            "reason": "input_not_provided"
          }
        },
        "error": null,
        "timestamp": "2026-04-01T10:01:05.000Z"
      }
    },
    "additionalVerifiedData": {}
  },
  "technicalData": {
    "ip": "127.0.0.1"
  }
}

{
  "status": "success",
  "verification": {
    "id": "12df6045-3846-3e45-946a-14fa6136d78b",
    "attemptId": "00bca969-b53a-4fad-b065-874d41a7b2b8",
    "vendorData": "12345678",
    "endUserId": "a1b2c35d-e8f7-6d5e-3cd2-a1b2c35db3d4",
    "status": "declined",
    "code": 9102,
    "reason": "Consent not obtained",
    "reasonCode": 640,
    "decisionTime": "2026-04-01T10:01:05.916Z",
    "acceptanceTime": "2026-04-01T10:00:27.000Z",
    "submissionTime": "2026-04-01T10:01:00.736Z",
    "person": {
      "firstName": "JUAN",
      "lastName": "GARCIA",
      "dateOfBirth": null,
      "gender": null,
      "nationality": null,
      "idNumber": null,
      "yearOfBirth": null,
      "placeOfBirth": null
    },
    "document": {
      "number": "000000000",
      "type": "ID_CARD",
      "country": "MX",
      "state": null
    },
    "registryValidations": {
      "MX_INE": {
        "status": "failure",
        "data": null,
        "validations": {
          "consent_obtained": {
            "result": "failure",
            "reason": "input_not_provided"
          },
          "person_registered": {
            "result": "not_applicable",
            "reason": "input_not_provided"
          },
          "selfie_registry_match": {
            "result": "not_applicable",
            "reason": "input_not_provided"
          },
          "not_reported_lost_or_stolen": {
            "result": "not_applicable",
            "reason": "input_not_provided"
          }
        },
        "error": null,
        "timestamp": null
      }
    },
    "additionalVerifiedData": {}
  },
  "technicalData": {
    "ip": null
  }
}

{
  "status": "success",
  "verification": {
    "id": "12df6045-3846-3e45-946a-14fa6136d78b",
    "attemptId": "00bca969-b53a-4fad-b065-874d41a7b2b8",
    "vendorData": "12345678",
    "endUserId": "a1b2c35d-e8f7-6d5e-3cd2-a1b2c35db3d4",
    "status": "declined",
    "code": 9102,
    "reason": "Selfie mismatch",
    "reasonCode": 581,
    "decisionTime": "2026-04-01T10:01:05.916Z",
    "acceptanceTime": "2026-04-01T10:00:27.000Z",
    "submissionTime": "2026-04-01T10:01:00.736Z",
    "person": {
      "firstName": "JUAN",
      "lastName": "GARCIA",
      "dateOfBirth": null,
      "gender": null,
      "nationality": null,
      "idNumber": "GARJ000000HMCRLP00",
      "yearOfBirth": null,
      "placeOfBirth": null
    },
    "document": {
      "number": "000000000",
      "type": "ID_CARD",
      "country": "MX",
      "state": null
    },
    "registryValidations": {
      "MX_INE": {
        "status": "failure",
        "data": null,
        "validations": {
          "consent_obtained": {
            "result": "success",
            "reason": null
          },
          "person_registered": {
            "result": "success",
            "reason": null
          },
          "selfie_registry_match": {
            "result": "failure",
            "reason": "selfie_mismatch"
          },
          "not_reported_lost_or_stolen": {
            "result": "not_applicable",
            "reason": "selfie_mismatch"
          },
          "first_name_match": {
            "result": "not_applicable",
            "reason": "selfie_mismatch"
          },
          "father_last_name_match": {
            "result": "not_applicable",
            "reason": "selfie_mismatch"
          },
          "mother_last_name_match": {
            "result": "not_applicable",
            "reason": "selfie_mismatch"
          },
          "personal_number_match": {
            "result": "not_applicable",
            "reason": "selfie_mismatch"
          },
          "registration_year_match": {
            "result": "not_applicable",
            "reason": "selfie_mismatch"
          },
          "issue_year_match": {
            "result": "not_applicable",
            "reason": "selfie_mismatch"
          }
        },
        "error": null,
        "timestamp": "2026-04-01T10:01:05.000Z"
      }
    },
    "additionalVerifiedData": {}
  },
  "technicalData": {
    "ip": null
  }
}

{
  "status": "success",
  "verification": {
    "id": "12df6045-3846-3e45-946a-14fa6136d78b",
    "attemptId": "00bca969-b53a-4fad-b065-874d41a7b2b8",
    "vendorData": "12345678",
    "endUserId": "a1b2c35d-e8f7-6d5e-3cd2-a1b2c35db3d4",
    "status": "declined",
    "code": 9102,
    "reason": "Value mismatch",
    "reasonCode": 904,
    "decisionTime": "2026-04-01T10:01:05.916Z",
    "acceptanceTime": "2026-04-01T10:00:27.000Z",
    "submissionTime": "2026-04-01T10:01:00.736Z",
    "person": {
      "firstName": "JUAN",
      "lastName": "GARCIA",
      "dateOfBirth": null,
      "gender": null,
      "nationality": null,
      "idNumber": "GARJ000000HMCRLP00",
      "yearOfBirth": null,
      "placeOfBirth": null
    },
    "document": {
      "number": "000000000",
      "type": "ID_CARD",
      "country": "MX",
      "state": null
    },
    "registryValidations": {
      "MX_INE": {
        "status": "failure",
        "data": null,
        "validations": {
          "consent_obtained": {
            "result": "success",
            "reason": null
          },
          "person_registered": {
            "result": "success",
            "reason": null
          },
          "selfie_registry_match": {
            "result": "not_applicable",
            "reason": "selfie_mismatch"
          },
          "not_reported_lost_or_stolen": {
            "result": "failure",
            "reason": "value_mismatch"
          },
          "first_name_match": {
            "result": "not_applicable",
            "reason": "value_mismatch"
          },
          "father_last_name_match": {
            "result": "not_applicable",
            "reason": "value_mismatch"
          },
          "mother_last_name_match": {
            "result": "not_applicable",
            "reason": "value_mismatch"
          },
          "personal_number_match": {
            "result": "not_applicable",
            "reason": "value_mismatch"
          },
          "registration_year_match": {
            "result": "not_applicable",
            "reason": "value_mismatch"
          },
          "issue_year_match": {
            "result": "not_applicable",
            "reason": "value_mismatch"
          }
        },
        "error": null,
        "timestamp": "2026-04-01T10:01:05.000Z"
      }
    },
    "additionalVerifiedData": {}
  },
  "technicalData": {
    "ip": null
  }
}

{
  "status": "success",
  "verification": {
    "id": "12df6045-3846-3e45-946a-14fa6136d78b",
    "attemptId": "00bca969-b53a-4fad-b065-874d41a7b2b8",
    "vendorData": "12345678",
    "endUserId": "a1b2c35d-e8f7-6d5e-3cd2-a1b2c35db3d4",
    "status": "declined",
    "code": 9102,
    "reason": "Registry unavailable",
    "reasonCode": 901,
    "decisionTime": "2026-04-01T10:01:05.916Z",
    "acceptanceTime": "2026-04-01T10:00:27.000Z",
    "submissionTime": "2026-04-01T10:01:00.736Z",
    "person": {
      "firstName": "JUAN",
      "lastName": "GARCIA",
      "dateOfBirth": null,
      "gender": null,
      "nationality": null,
      "idNumber": null,
      "yearOfBirth": null,
      "placeOfBirth": null
    },
    "document": {
      "number": "000000000",
      "type": "ID_CARD",
      "country": "MX",
      "state": null
    },
    "registryValidations": {
      "MX_INE": {
        "status": "error",
        "data": null,
        "validations": null,
        "error": {
          "code": "registry_error",
          "message": "registry_unavailable"
        },
        "timestamp": null
      }
    },
    "additionalVerifiedData": {}
  },
  "technicalData": {
    "ip": null
  }
}

Request properties explained

• status: string Status of the response

• verification: object Verification request decision object. null if decision is not available yet

  • id: string UUID v4 which identifies the verification session

  • attemptId: string UUID v4 of the attempt which received a status (as shown in verification.status field)

  • vendorData: string | null The unique identifier that you created for your end-user. null if not specified

  • endUserId: string | null The UUID that you created for your end-user. null if not specified

  • status: string Verification status, one of approved, declined, resubmission_requested, expired, abandoned

  • code: integer Verification session decision code, one of 9001, 9102, 9103, 9104. For more info, see the verification session decision codes article

  • reason: string | null Reason why the verification failed. For more info, see the status and reason codes section below

  • reasonCode: integer | null Reason code of the failed verification

  • decisionTime: string | null Timestamp of the decision, represented as UTC YYYY-MM-DDTHH:MM:SS.SSS+Timezone Offset (ISO 8601)

  • acceptanceTime: string Timestamp of the session generation, represented as UTC YYYY-MM-DDTHH:MM:SS.SSS+Timezone Offset (ISO 8601)

  • submissionTime: string Timestamp of when the session was submitted, represented as UTC YYYY-MM-DDTHH:MM:SS.SSSSSS+Timezone Offset (ISO 8601)

  • person: object Data about the verified person

    • firstName: string | null Person's first name

    • lastName: string | null Person's father's last name

    • dateOfBirth: string | null Person's date of birth, represented as YYYY-MM-DD

    • gender: string | null Person's gender, represented as M or F, or null if not present

    • nationality: string | null Person's nationality, represented as ISO 3166 alpha-2 or alpha-3 code

    • idNumber: string | null Person's CURP

    • yearOfBirth: string | null Person's year of birth, represented as YYYY

    • placeOfBirth: string | null Person's place of birth

  • document: object Data about verified document

    • number: string | null The 9-digit CIC, [0-9] characters only

    • type: string | null Document type, always ID_CARD

    • country: string | null Document issuing country, represented as ISO 3166 alpha-2 code, always MX

    • state: string | null Document issuing state, represented as ISO 3166 alpha-2 or alpha-3 code

  • registryValidations: object Registry validation results for this session

    • MX_INE: object Results of the Mexican INE registry check

      • status: string Overall result of the registry check: success, failure, or error

      • data: null Always null because the INE registry does not return person data, it only confirms or denies matches

      • validations: object | null Map of validation results. null when status is error

        • consent_obtained: object Whether the end-user's INE consent was provided

          • result: string Validation result

          • reason: string | null Reason for the result

        • person_registered: object Whether the person was found in the INE registry

          • result: string Validation result

          • reason: string | null Reason for the result

        • selfie_registry_match: object Whether the submitted selfie matches the registry portrait

          • result: string Validation result

          • reason: string | null Reason for the result

        • not_reported_lost_or_stolen: object Whether the voter card has not been reported as lost or stolen

          • result: string Validation result

          • reason: string | null Reason for the result

        • first_name_match: object Whether the provided first name matches the INE registry

          • result: string Validation result

          • reason: string | null Reason for the result

        • father_last_name_match: object Whether the provided father's last name matches the INE registry

          • result: string Validation result

          • reason: string | null Reason for the result

        • mother_last_name_match: object Whether the provided mother's last name matches the INE registry

          • result: string Validation result

          • reason: string | null Reason for the result

        • personal_number_match: object Whether the provided CURP matches the INE registry

          • result: string Validation result

          • reason: string | null Reason for the result

        • registration_year_match: object Whether the provided document registration year matches the INE registry

          • result: string Validation result

          • reason: string | null Reason for the result

        • issue_year_match: object Whether the provided document issue year matches the INE registry

          • result: string Validation result

          • reason: string | null Reason for the result

      • error: object | null Error details when status is error. null otherwise

        • code: string Machine-readable error code, always registry_error

        • message: string Error description, one of registry_unavailable, technical_issues

      • timestamp: string | null ISO-8601 timestamp of when the registry responded. null when the registry was not reached

  • additionalVerifiedData: object Data that has been optionally verified for the session. Returns empty {} if no additional data was verified

  • comments: array (Deprecated) Always returns empty []

• technicalData: object Technical data object

  • ip: string | null IP address of the device from which the verification was made

API call

Sample response

The API response payload is identical to decision webhook payload. See the sample payload above.

Response properties explained

The API response payload is identical to decision webhook payload. See the request properties explained above.

Veriff Customer Portal

You can find the verification session related info, including the decision, in the Veriff Customer Portal, under the Webhooks tab.

Status and reason codes

Veriff runs a series of automated checks on the submitted data and biometric information. At the end, a decision is produced and delivered via webhook.

As the primary decision signal see:

• verification.code for verification session decision code, one of 9001, 9102, 9103, 9104

• verification.status for verification decision status, one of approved, declined, resubmission_requested, expired, abandoned

If the INE Biometric Database Verification session was declined, you can find additional information by checking:

• verification.reason for the reason why the verification failed

• verification.reasonCode for the reason code of the failed verification and cross-reference it with Granular reason codes (table)

How to interpret reasonCode and reason fields?

Use the verification.reasonCode to determine what kind of problem occurred and to create programmatic actions based on rejection outcomes.

Use the verification.reason for logging, display, and human interpretation only.

The verification.reasonCode is produced by registry match validations aka validations that run against the actual registry response (e.g., "did the selfie match?"). These come from a flat list of integer constants, meaning they are deliberate, stable, machine-readable signals that can be used for integration logic.

The verification.reason is a human-readable text string that describes why a verification was not approved.

• The value is derived from the specific reason behind the registry validation that failed: for example, a name match check or a selfie match check. Each of these validations can fail for multiple different reasons (e.g., a name match can fail because the value did not match, or because the registry was unavailable). The reason field surfaces whichever specific reason applied in that session.

• Because of this, there is no 1:1 relationship between reasonCode and reason. Values like registry_unavailable or technical_issues can appear under any reasonCode because they indicate that the relevant validation could not complete, not that the match itself failed. For more detail on how validation failure reasons propagate, see the Validation cascade → Cascade rules section.

* The "default behaviour" column reflects the session outcome on a default configuration. Veriff can configure some of these validations differently per your request (e.g., turning a decline into a resubmission, or ignoring a check entirely).

** The "typical value" reflects the core failure condition of that validation. Other values can appear when the validation could not complete normally — for example, due to registry unavailability, missing input, or a disabled validation.

Additional information

Best practices

1. CIC format validation: validate the CIC format client-side before creating a session. The CIC must be exactly digits. Passing an invalid CIC will result in a session failure.

2. CURP format validation: if you send the CURP (verification.person.idNumber), validate its format client-side. A valid CURP is 18 characters in the format AAAA######AAAAAA##. Passing an incorrectly formatted CURP will cause the the whole session to fail with and person_registered.result: failure and person_registered.reason: input_invalid.

3. Consent validation: ensure consents includes {"type": "ine", "approved": "true"} before creating the session. A missing or false value causes an immediate decline with reasonCode 640.

4. Selfie image quality: ensure the end-user's selfie is a good quality, front-facing image with adequate lighting. The face similarity threshold is 80% by default, and poor image quality increases the risk of false negatives.

5. Error handling: implement proper error handling for all three MX_INE.status values: success, failure, and error. When status is error, check error.code and error.message to determine whether to retry.

6. Session declined due to third-party provider issues: implement proper session handling when a legitimate end-user's session is declined due to third-party service provider issues, as indicated by reasonCode 901. In case of upstream INE/FIMPE connectivity issues, Veriff retries up to 2 times internally before returning this error. Consider implementing retry logic with exponential backoff on your side for 901 errors.

7. Webhook security: secure your webhook endpoint and verify request signatures. See HMAC Authentication and Endpoint Security for more info.

8. User experience: provide clear feedback to users about validation results. Inform end-users what their INE consent covers (biometric data processing against the INE registry) before session creation.

9. Ensure backwards compatibility for webhooks and API connections

Changelog