How to Add NIN and BVN Verification to Your Nigerian Web App

If you are building anything in Nigeria that needs to confirm a user is genuinely who they claim to be, a lending app, a marketplace with seller accounts, a service handling any real money, you will eventually need identity verification, checking a National Identification Number or a Bank Verification Number against the official record it belongs to. This is a practical, developer-focused guide to how that integration actually works, the real providers available, and the specific things worth getting right, written for someone about to build this, not someone comparing which vendor to buy from.

Why you cannot verify a NIN or BVN yourself, directly

Nigeria's National Identification Number database is held by the National Identity Management Commission, and Bank Verification Numbers are held within the banking system's own shared infrastructure. Neither is a database an individual business can query directly on its own; access runs through licensed intermediaries, commercial verification providers who have been granted API access to check a submitted number against the official record and return a match or no-match result, along with whatever basic confirmed details the specific check permits, typically a name, sometimes limited demographic details, never the full underlying record itself. Understanding this structure, you as a business go through a licensed provider, not directly to government infrastructure, shapes every practical decision that follows.

The real providers you will actually choose between

Several commercial providers offer NIN and BVN verification APIs to Nigerian developers, each with broadly similar core functionality and genuinely different pricing, documentation quality, and additional features. Prembly, also known by its Identitypass product name, offers verification across NIN, BVN and driver's licence checks through a straightforward REST API. QoreID offers a comparable range of checks with its own authentication flow. Youverify positions itself more broadly as a full KYC and compliance platform, with identity verification as one part of a wider offering. Dojah offers both standard NIN verification and a newer, more privacy-conscious virtual NIN variant, alongside photo retrieval directly from the government record where the specific check permits it.

None of these is a fixed, permanent recommendation, since pricing and feature sets in this space shift over time, and the sensible approach for any real project is comparing current documentation and pricing directly from each provider's own site at the time you are actually building, rather than trusting a specific comparison that will inevitably age.

What a typical verification request actually looks like

Stripped to its essentials, a NIN verification request is a straightforward REST API call, following the same general shape covered in our guide to REST APIs explained for beginners: your server sends a request to the provider's endpoint, carrying the NIN or BVN number to check and your API credentials, and receives back a response indicating whether the number matches a real, valid record, along with whatever confirmed details the specific check returns. As with any API handling sensitive personal information, this request must happen from your own server, never directly from a visitor's browser, following the architecture discipline covered in our guide to connecting an API to a website, since your provider credentials, and the sensitive identity number itself, should never be exposed to the browser.

Handling the result properly: what "verified" actually tells you

A successful verification confirms that the number submitted genuinely belongs to a real person in the official record, and that whatever basic details you received, typically a name, match what was checked. It does not, on its own, confirm that the person submitting the number is genuinely that person, since a NIN or BVN, once known, could in principle be entered by someone other than its owner. For a use case where this distinction genuinely matters, lending, financial services, anything with real fraud risk, pair number verification with an additional check, a selfie compared against a photo on record where the provider supports it, or an out-of-band confirmation like a one-time code sent to the phone number on file, rather than treating a bare number match alone as full proof of identity.

Handling failures and near-matches honestly

A verification check can fail for entirely mundane reasons that have nothing to do with fraud: a genuine typo in the number, a record with a discrepancy between how a name is formally recorded and how a user typed it, or a temporary issue on the provider's own side. Build your failure handling to communicate this honestly to the user, "we could not verify this number, please check it and try again," rather than a message implying suspicion or wrongdoing, since the overwhelming majority of failed verifications are innocent, correctable mistakes, not fraud attempts, and treating every failure as suspicious produces a genuinely poor experience for the honest majority.

Rate limits, cost, and testing without burning through real credits

Every provider charges per verification check, typically a modest amount per successful lookup, and most offer a sandbox or test mode with either free test credits or clearly documented test numbers that return predictable, safe results without consuming real, paid credits or touching a real person's actual data. Build and test your entire integration against this sandbox mode thoroughly, following the same testing discipline covered throughout our API integration guides, before switching to live credentials and beginning to incur real, per-check costs against genuine customer data.

Data protection: this is genuinely sensitive information

A NIN or BVN is meaningfully sensitive personal data, and handling it deserves the same seriousness as handling payment information. Never log the raw number in plain, easily accessible logs longer than genuinely necessary for debugging. Store only what your actual business purpose requires, often just a confirmation that verification succeeded and the confirmed name, not the raw number itself retained indefinitely. And ensure your data handling complies with Nigeria's data protection regulation, covered briefly in our broader guide to starting an online business in Nigeria, which applies squarely to identity information of exactly this kind.

Comparing providers on the dimensions that actually matter for a real build

Rather than a fixed recommendation, here are the dimensions worth actually comparing when choosing, since the right provider genuinely depends on your specific use case. Coverage: confirm the provider supports every specific check type your product needs, NIN, BVN, and driver's licence or voter's card if relevant, since not every provider covers every type equally well. Response time: identity checks that hold up a user during onboarding need to feel fast, and a provider's genuine, typical response time, not just its marketing claim, is worth testing directly against your own sandbox account before committing. Documentation quality: a provider with clear, current, example-rich documentation saves real development time compared with one whose docs are thin or out of date, and this is worth judging for yourself by actually reading through a provider's docs before signing up, not assuming from their marketing page alone. Pricing structure: some charge a flat rate per check, others tier pricing by volume, and the right structure depends on your expected real volume, worth modelling against your own actual, realistic usage rather than a generic comparison.

Building a graceful degradation path for provider downtime

Any single verification provider can experience downtime or a temporary outage, and a business entirely dependent on identity verification for every single onboarding needs a plan for this, rather than simply blocking every new user the moment a provider becomes unreachable. Depending on your actual risk tolerance, this might mean a manual review queue that temporarily accepts new users pending verification once the provider is confirmed working again, or, for a lower-stakes use case, a temporary relaxation of the requirement with clear internal tracking of who was onboarded during the gap for later, retroactive verification. Whichever approach fits your specific business, deciding this in advance, before a real outage forces an improvised decision under pressure, is worth the planning time.

Webhook-based verification versus synchronous requests

Some providers return a verification result immediately, within the same request-response cycle, suitable for a use case where the user is actively waiting during onboarding and a few seconds' delay is acceptable. Others, particularly for more thorough checks involving additional cross-referencing, may process asynchronously and notify you of the result through a webhook, following the same general pattern covered in our guide to what a webhook is, including the same signature verification discipline covered there, since a webhook claiming a verification result is genuine deserves exactly the same scepticism and cryptographic confirmation as a payment webhook claiming a transaction succeeded. Confirm which pattern your chosen provider actually uses before designing your user interface around an assumption that turns out to be wrong.

A note on the virtual NIN option, where available

Some providers, Dojah specifically at the time of writing, support a virtual NIN variant, a temporary, revocable token a user generates themselves through an official NIMC channel rather than sharing their permanent, unchangeable NIN directly with your business. Where this option is genuinely available and suits your use case, it offers a real privacy advantage for the user, since a compromised virtual NIN token can be revoked and reissued, unlike a permanent NIN number, which cannot meaningfully be changed if it is ever exposed. Consider offering this as an option to your users where your chosen provider supports it, alongside standard NIN verification, rather than only supporting the less privacy-friendly permanent-number approach by default.

A worked example: adding verification to an imagined lending app's onboarding

Picture a small lending platform building its user onboarding flow, needing to confirm a new applicant's identity before approving any loan. The flow asks for a NIN during signup, sends it from the server, never the browser, to a verification provider's sandbox endpoint during development, and handles three distinct outcomes explicitly: a clean match, proceeding to the next onboarding step; a mismatch, prompting the user to re-check and re-enter the number; and a provider error, distinct from a mismatch, retried automatically once before surfacing a clear "please try again shortly" message rather than confusing a temporary technical failure with a genuine identity mismatch.

Given the platform's genuine fraud risk as a lender, the team adds a second layer beyond the bare number check: a selfie captured during onboarding, compared against the photo the provider's response includes for this specific type of check, giving a materially stronger identity signal than the number match alone before any lending decision is made. Testing runs entirely against the provider's documented sandbox test numbers until the full flow, success, mismatch, and provider-error handling, is confirmed working correctly, only then switching to live credentials before real applicants begin using it.

Regulatory context worth being aware of, briefly

This is not legal advice, and a proper compliance conversation with a qualified professional is worth having for any business genuinely built around identity verification at scale, but a few points are worth knowing as a developer. The Central Bank of Nigeria's know-your-customer requirements apply to many financial services businesses specifically, and NIMC's own terms govern how NIN data may be used and retained by any business accessing it, even through a licensed intermediary provider. Building your data retention and usage policy with these obligations genuinely in mind from the start, rather than retrofitting compliance after a product is already live and handling real user data, is considerably less painful and less risky than the alternative.

Testing checklist before going live with real users

Confirm every request happens from your own server, never a visitor's browser, with credentials properly stored as environment variables rather than in code. Test every documented outcome in the provider's sandbox, a clean match, a deliberate mismatch, and a simulated provider error, confirming your application handles each distinctly and correctly. Confirm you are not logging or storing the raw identity number anywhere beyond what your actual business purpose genuinely requires. If using a webhook-based provider, confirm signature verification is properly implemented and tested, not just assumed correct. And have a documented plan for provider downtime before it happens for real, rather than improvising one during an actual outage affecting real users trying to sign up.

Mistakes to avoid building this

Verifying from the browser rather than your own server, exposing both your provider credentials and the user's sensitive number. Treating every failed verification as suspicious rather than the innocent, correctable mistake it usually is. Storing raw NIN or BVN numbers longer or more visibly than your actual business purpose requires. Testing exclusively against real numbers and real credits rather than using the sandbox mode every serious provider offers. And treating a bare number match as complete proof of identity for a use case where the fraud stakes genuinely call for a stronger, second verification signal.

Where this fits into a Nigerian verification-heavy business

Our own verification solution template is built around this same bring-your-own-provider pattern, letting you connect a real Prembly, QoreID, Youverify or Dojah account, similar to how our VTU template lets you connect your own vending provider rather than us supplying access ourselves. Because this integration depends entirely on your own provider account and its current, live behaviour, we would rather be straightforward than overstate it: test any specific provider's actual current behaviour thoroughly against your own account before depending on it for a real, live decision. If you are building something with genuine, high-stakes verification needs, our custom software service can help build and properly test the specific flow your business needs.