Skip to content
Speedmap
Create an account

Identity

BVN verification through NIBSS

Check up to six customer details against a BVN with no personal data returned, or fetch the full record after NIBSS Consent Hub approval.

Create an account Read the docs

What it does

BVN Verification, in detail.

Field-by-field BVN checks

Boolean takes up to six details (first_name, middle_name, last_name, date_of_birth, phone, gender) and returns a yes/no per detail in field_matches.

No personal data back

Boolean never returns the record, and it is the only BVN method on Speedmap Connect.

Full record with consent

Core requires a consent_id granted through NIBSS Consent Hub, checked before anything reaches NIBSS, and returns field_confidence 0–100 per name.

Watchlist flag

Core results carry the NIBSS watchlisted flag, which Fraud Signals also scores.

Consent on any phone

Subjects approve on a hosted page, by email link or by USSD, with a four-part category mask.

Methods

Every method returns the same normalized verification object. The method, consent mechanism and purpose code are stored with each result.

  • boolean

    Input
    BVN, reason, consent attestation, up to six details to check
    Returns
    match plus a yes/no per detail
    Consent
    Client attested
    Access
    All approved workspaces

  • core

    Input
    BVN, reason, consent_id
    Returns
    Full record (full tier) or assertion
    Consent
    NIBSS Consent Hub grant
    Access
    All approved workspaces

How it works

From request to decision.

  1. 1

    Choose boolean or core

    Boolean to confirm details you collected; core when you have a lawful need for the record.

  2. 2

    Request consent for core

    POST /v1/consents creates a link, email or USSD code, and the subject approves with an OTP.

  3. 3

    Verify

    POST /v1/verify/bvn, with the consent_id for core; consent can be revoked at any time.

Routing and providers

BVN checks run on the NIBSS Financial Authentication Service. Consent runs through NIBSS Consent Hub and iGree.

Use it

One request. One normalized response.

Call POST /v1/verify/bvn through @speedmap/node, speedmap for Python, or the verify_bvn tool in Speedmap Connect.

Read the guide API reference
Request
curl -X POST http://localhost:4000/v1/verify/bvn \
  -H "Authorization: Bearer sk_test_..." \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
  "method": "boolean",
  "bvn": "22222222221",
  "reason": "financialProducts",
  "consent": {
    "obtained": true
  },
  "match": {
    "first_name": "Clarke",
    "last_name": "Griffin",
    "date_of_birth": "1992-04-18",
    "phone": "08031234567"
  }
}'
Response · 200 OK
{
  "reference_id": "spm_f61e650f69b5766b2197fe45",
  "object": "verification",
  "product": "bvn",
  "method": "bvn_boolean",
  "status": "verified",
  "match": true,
  "field_matches": {
    "first_name": true,
    "last_name": true,
    "date_of_birth": true,
    "phone": true
  },
  "field_confidence": null,
  "mode": "sandbox",
  "reason": "financialProducts",
  "subject": "*******2221",
  "summary": {
    "match": true,
    "repeat_count_30d": 1,
    "repeat_platform_bucket": "0"
  },
  "consent": {
    "mechanism": "client_attested",
    "consent_id": null
  }
}

Use cases

Where Nigerian teams use it.

Loan origination

Confirm the applicant’s declared details against their BVN before disbursement, without storing the record.

Seller onboarding

Check a sole trader’s BVN and watchlist flag before the first payout.

Account recovery

Use a boolean check as step-up when a customer changes phone number or device.

Insurance claims

Match the claimant to the policyholder before a payout leaves the float.

Part of:LendingPayments & payouts

What you get back

The fields you will read.

  • status

    Meaning
    verified, not_found, pending or failed

  • match

    Meaning
    Whether every detail you sent agrees with the record

  • field_matches

    Meaning
    Yes/no per detail you sent

  • field_confidence

    Meaning
    Core: 0–100 per name field, tolerant of nicknames and spellings (null for boolean)

  • subject

    Meaning
    The BVN, masked

  • summary.watchlisted

    Meaning
    Core: NIBSS industry watchlist flag

  • consent

    Meaning
    client_attested, or nibss_consent_hub with the consent_id and timestamp

Assertion tier

Boolean results never contain personal data, whatever your tier.

Full tier

Core results on the full tier add data: names, date of birth, gender, marital status, nationality, phone numbers, email, linked NIN, origin, residence, enrolment details, watchlist flag and photo.

Pricing

Billed per live check on the Scale up plan. Failed calls and idempotent retries are never billed.

DocumentationSee pricing plans

FAQ

BVN Verification questions.

Need more detail? Read the documentation or talk to our team.

What is the difference between boolean and core?
Boolean returns match and a yes/no per detail, with no personal data. Core returns the full record and needs a NIBSS Consent Hub grant.
Does a boolean check need consent?
You attest that you obtained consent for the stated purpose, and the attestation is stored with the verification.
Can customers without smartphones consent?
Yes. With the USSD channel the subject approves by dialling a short code on any phone.

Start verifying in minutes. Go live when you’re ready.

Create your account in under a minute and explore the full dashboard. We switch your workspace live after a short compliance review.

Create an account Read the quickstart