LumiID Python SDK: Nigerian Identity Verification in Python

The LumiID Python SDK wraps the LumiID Identity Verification API so you can verify Nigerian identity records directly from your Python application. Use it to run KYC, business verification, payment validation, and fraud-prevention checks against NIN, BVN, CAC, TIN, and NUBAN records. The SDK exposes a single client.verify() method that covers every supported ID type, raises typed exceptions for every error case, and supports advanced lookups for enriched data where available. Install it with pip install lumiid. Python 3.8 or later is required.

Installation

Install the package from PyPI:

pip install lumiid

The SDK automatically installs requests >= 2.28.0 as a dependency.

Authentication

Obtain your API key from the LumiID dashboard and pass it when creating the client. The recommended approach is to read it from an environment variable:

import os
from lumiid import LumiID

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

Store your API key in an environment variable or secret manager — never hardcode it in source code or commit it to version control.

Quick Start

Verify a NIN in three lines once the client is configured:

import os
from lumiid import LumiID

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

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

Verification Examples

Every ID type uses the same client.verify() method. Pass the id_type, id_number, and optionally advance=True for enriched results where supported.

NIN Verification

Verify an 11-digit National Identification Number (NIN). Pass advance=True to fetch the full NIMC profile.

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

# Advanced NIN (full NIMC profile)
result = client.verify(id_type="NIN", id_number="12345678901", advance=True)
print(result)

BVN Verification

Verify an 11-digit Bank Verification Number (BVN). Advanced lookup is available.

# Basic BVN verification
result = client.verify(id_type="BVN", id_number="12345678901")
print(result)

# Advanced BVN
result = client.verify(id_type="BVN", id_number="12345678901", advance=True)
print(result)

CAC Business Verification

Verify a Nigerian Corporate Affairs Commission (CAC) registration number. Use the RC prefix, for example RC1234567. Pass advance=True to retrieve directors and shareholders.

# Basic CAC verification
result = client.verify(id_type="CAC", id_number="RC1234567")
print(result)

# Advanced CAC (includes directors and shareholders)
result = client.verify(id_type="CAC", id_number="RC1234567", advance=True)
print(result)

TIN Verification

Verify a Nigerian Tax Identification Number (TIN). TIN supports basic verification only.

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

NUBAN Account Verification

Verify a 10-digit Nigerian Uniform Bank Account Number (NUBAN). NUBAN supports basic verification only.

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

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

Error Handling

The SDK raises typed exceptions so you can handle each failure case precisely. Always catch specific exceptions before the base LumiIDError.

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

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

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

except AuthenticationError:
    print("Invalid or missing API key")

except ValidationError as e:
    print(f"Validation error: {e.message}")

except RateLimitError:
    print("Rate limit exceeded — back off and retry")

except LumiIDError as e:
    print(f"API error: {e.status_code} — {e.response}")

except ValueError as e:
    print(f"Invalid input: {e}")

Exception Reference

Exception	When raised	Useful attributes
`AuthenticationError`	Invalid or missing API key	—
`ValidationError`	API rejected the input data	`message`
`RateLimitError`	Request rate limit exceeded	—
`LumiIDError`	General API or network error	`status_code`, `response`
`ValueError`	Invalid local input format (e.g. NIN is not 11 digits)	`message`

Client Configuration

The LumiID constructor accepts two parameters:

Parameter	Type	Default	Description
`api_key`	str	required	Your LumiID API key from the dashboard.
`timeout`	int	`30`	Request timeout in seconds.

Increase timeout if you’re on a slower network or experiencing intermittent timeouts:

import os
from lumiid import LumiID

client = LumiID(
    api_key=os.getenv("LUMIID_API_KEY"),
    timeout=60  # increase for slower networks
)

Requirements

Requirement	Version
Python	3.8 or later
`requests`	2.28.0 or later (installed automatically)

Get Started

General

Government Verification

Business Verification

Biometric & AML

SDKs & Integration

Reference

LumiID Python SDK: Nigerian Identity Verification in Python

Installation

Authentication

Quick Start

Verification Examples

NIN Verification

BVN Verification

CAC Business Verification

TIN Verification

NUBAN Account Verification

Supported ID Types

Error Handling

Exception Reference

Client Configuration

Requirements

​Installation

​Authentication

​Quick Start

​Verification Examples

​NIN Verification

​BVN Verification

​CAC Business Verification

​TIN Verification

​NUBAN Account Verification

​Supported ID Types

​Error Handling

​Exception Reference

​Client Configuration

​Requirements

Installation

Authentication

Quick Start

Verification Examples

NIN Verification

BVN Verification

CAC Business Verification

TIN Verification

NUBAN Account Verification

Supported ID Types

Error Handling

Exception Reference

Client Configuration

Requirements