Dashboard →
Python SDK Identity Verification — Nigeria

Verify Nigerian IDs
in three lines of code.

LumiID gives your application instant access to NIN, BVN, CAC, TIN, and NUBAN verification through a clean, idiomatic Python SDK.

$ pip install lumiid
NIN BVN CAC TIN NUBAN Python 3.8+ MIT License

Overview

LumiID is a clean, minimal Python SDK wrapping the LumiID Identity Verification API. It provides developer-friendly access to five Nigerian identity systems with consistent error handling, optional advanced lookups, and sane defaults.

Zero boilerplate

One method — client.verify() — covers every ID type.

Typed exceptions

Every error case maps to a specific exception class you can catch precisely.

Advanced mode

Pass advance=True for premium enriched results on NIN, BVN, and CAC.

Installation

Install from PyPI using pip:

Requires Python 3.8+. The only dependency is requests >= 2.28.0, which is installed automatically.

Authentication

Obtain your API key from the LumiID dashboard. Pass it when instantiating the client.

Hardcoded key (not recommended) 
from lumiid import LumiID

client = LumiID(api_key="your_api_key_here")
✦ Recommended — environment variable 
import os
from lumiid import LumiID

client = LumiID(api_key=os.getenv("LUMIID_API_KEY"))

Never commit your API key to version control. Add LUMIID_API_KEY to your .env file and keep it in .gitignore.

Quick Start

Verify a NIN in under a minute:

from lumiid import LumiID

client = LumiID(api_key="your_api_key_here")

result = client.verify(id_type="NIN", id_number="12345678901")
print(result)
NIN

National Identification Number

11-digit number issued by the National Identity Management Commission (NIMC). Supports basic and advanced (premium) lookups.

Basic verification
result = client.verify(id_type="NIN", id_number="12345678901")
print(result)
✦ Advanced / premium verification
result = client.verify(id_type="NIN", id_number="12345678901", advance=True)
print(result)
BVN

Bank Verification Number

11-digit number issued by the Central Bank of Nigeria (CBN) to bank customers. Supports basic and advanced lookups.

Basic verification
result = client.verify(id_type="BVN", id_number="12345678901")
print(result)
✦ Advanced / premium verification
result = client.verify(id_type="BVN", id_number="12345678901", advance=True)
print(result)
CAC

Corporate Affairs Commission

Registration number for Nigerian businesses, formatted as RC followed by digits (e.g. RC1234567). Supports basic and advanced lookups.

Basic verification
result = client.verify(id_type="CAC", id_number="RC1234567")
print(result)
✦ Advanced / premium verification
result = client.verify(id_type="CAC", id_number="RC1234567", advance=True)
print(result)
TIN

Tax Identification Number

Issued by the Federal Inland Revenue Service (FIRS). Format: 12345678-0001. Basic verification only.

result = client.verify(id_type="TIN", id_number="12345678-0001")
print(result)
NUBAN

Nigerian Uniform Bank Account Number

10-digit standardised account number used across all Nigerian banks. Basic verification only.

result = client.verify(id_type="NUBAN", id_number="1234567890")
print(result)

Error Handling

The SDK raises typed exception classes so you can handle each failure case exactly. Import them alongside LumiID:

import os
from lumiid import (
    LumiID,
    LumiIDError,
    AuthenticationError,
    ValidationError,
    RateLimitError,
)

client = LumiID(api_key=os.getenv("LUMIID_API_KEY"))

try:
    result = client.verify(id_type="NIN", id_number="12345678901")
    print(result)

except AuthenticationError:
    # Invalid or missing API key
    print("Check your API key.")

except ValidationError as e:
    # API rejected the input data
    print(f"Validation failed: {e}")

except RateLimitError:
    # Exceeded API quota / wallet balance depleted
    print("Rate limit exceeded. Check your LumiID wallet balance.")

except LumiIDError as e:
    # General API or network error
    print(f"API error {e.status_code}: {e}")
    print(f"Full response: {e.response}")

except ValueError as e:
    # Invalid input format — e.g. NIN is not 11 digits
    print(f"Invalid input: {e}")

Exception Reference

Exception When raised Useful attributes
AuthenticationError Invalid or missing API key —
ValidationError API rejected input data message
RateLimitError Wallet / quota exceeded —
LumiIDError General API / network error status_code, response
ValueError Invalid local input format message

Supported ID Types

id_type Full Name Format advance=True
NIN National Identification Number 11 digits ✓ yes
BVN Bank Verification Number 11 digits ✓ yes
CAC Corporate Affairs Commission RC + digits ✓ yes
TIN Tax Identification Number 00000000-0001 ✗ no
NUBAN Nigerian Uniform Bank Account Number 10 digits ✗ no

Configuration

Customise request timeout (default: 30 seconds):

client = LumiID(api_key="your_api_key_here", timeout=60)
Parameter Type Default Description
api_key str required Your LumiID API key
timeout int 30 Request timeout in seconds

Requirements

Python

3.8 or higher

requests

>= 2.28.0 (auto-installed)

Contributing

Pull requests are welcome. For major changes, please open an issue first to discuss what you'd like to change.

# 1. Fork the repository, then clone your fork
git clone https://github.com/omninile/lumiid-python-sdk.git

# 2. Create a feature branch
git checkout -b feature/add-passport-verification

# 3. Commit your changes with a conventional commit message
git commit -m 'feat: add passport verification'

# 4. Push and open a Pull Request
git push origin feature/add-passport-verification
Open an issue View on GitHub