> ## Documentation Index
> Fetch the complete documentation index at: https://docs.lumiid.com/llms.txt
> Use this file to discover all available pages before exploring further.

# LumiID Python SDK: Nigerian Identity Verification in Python

> Install the LumiID Python SDK to verify NIN, BVN, CAC, TIN, and NUBAN records from Python. Requires Python 3.8+. Install with pip install lumiid.

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:

```bash theme={null}
pip install lumiid
```

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

* [LumiID on PyPI](https://pypi.org/project/lumiid)
* [LumiID Python SDK on GitHub](https://github.com/lumiid/lumiid-python)

***

## 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:

```python theme={null}
import os
from lumiid import LumiID

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

> [!WARNING]
>
> 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:

```python theme={null}
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.

```python theme={null}
# 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.

```python theme={null}
# 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.

```python theme={null}
# 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.

```python theme={null}
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.

```python theme={null}
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`.

```python theme={null}
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:

```python theme={null}
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) |


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.