Skip to main content
Check the number an applicant gives you against the government record it belongs to: confirm it exists, that it’s theirs, and (where the registry has a photo) that their face matches.
A government database lookup is an optional part of the ID Verification step. When an applicant picks a supported ID type, deepidv asks for their identity number, gets their consent, queries the issuing registry, and compares what comes back with the applicant’s details. You only need this page if your workflow accepts one of the ID types below. Every other workflow behaves exactly as before.

Supported ID types

More countries are coming. The response shape on this page is the same for every ID type, so you won’t need to change your integration when we add more.

How it works

1

Enable the ID type in your workflow

In the workflow builder, add ID Verification and select the ID type under the country’s accepted documents: Nigeria → BVN or Nigeria → National ID (NIN), and Mexico → CURP.
2

The applicant enters their number

The applicant chooses the ID type and enters their number. For NIN and CURP they also photograph the card, and deepidv can read the number from it. BVN has no physical card, so it’s number-only.
3

Consent and lookup

The applicant agrees to the registry check. Then deepidv validates the number’s format and queries the registry. If the number is malformed, the registry isn’t called and you aren’t charged.
4

Match and face compare

deepidv compares the registry record with the applicant’s name and, where supported, their date of birth. If a selfie was captured, it’s also compared with the registry portrait (BVN, NIN) and with the photographed card (NIN, CURP).
5

Read the result

The result is attached to the session under analysis_data.identity_lookup_data. Retrieve it with Retrieve Session.

Reading the result

The verdict is identity_lookup_data.status. Use reason_code to decide what to do next.
status is the verdict for the lookup, not the session’s top-level status or analysis_data.id_matches_selfie. id_matches_selfie only reports whether the faces matched. It can be true while the lookup is NOT_VERIFIED, for example when the applicant used someone else’s number but a selfie that matches the registry photo.

status

reason_code

reason_text holds a readable explanation of the reason_code, suitable for showing to a reviewer.

Name matching

Names come back from registries in many forms (all caps, middle names, a different word order). A NAME_MISMATCH doesn’t always mean fraud. For example, a married name or a different spelling (Mohammed vs Muhammad) will also fail. Compare subject against your applicant before rejecting outright.

Example

A BVN lookup where the number exists but belongs to someone other than the applicant (all values are fictional):
The registry portrait is available as a temporary download link at resource_links.identity_lookup_photo on the same session. See the full field reference.

Good to know

  • The full number is never returned. You get id_number_masked (last four digits) and id_number_hash. The hash is stable per ID type, so you can use it to spot the same number across sessions.
  • Date of birth is matched for BVN and NIN only when the applicant provided one. Check field_validation to see which fields were actually compared.
  • Not every field applies to every ID type. Fields the registry doesn’t provide are null. For example, record_status is only populated for CURP, and watch_listed (true / false / null for unknown) can only be set for BVN.
  • Attempts are limited. An applicant gets up to 3 billable attempts per ID. billable_attempts shows how many were used, and several failed attempts on one session is worth a reviewer’s attention.
  • Billing. Each lookup that reaches the registry is billable, whether or not it matches. A number rejected as malformed is free.