> For the complete documentation index, see [llms.txt](https://docs.lumiid.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.lumiid.com/api-integration/sdks/lumiid-python-sdk-or-nigerian-identity-verification.md).

# LumiID Python SDK | Nigerian Identity Verification

## LumiID Python SDK

Verify Nigerian NIN, BVN, CAC, TIN, and NUBAN records from Python. Use the SDK for KYC, business verification, payment validation, and fraud-prevention workflows.

Install the package, set your API key, and call `client.verify()`.

```bash
pip install lumiid
```

|                      |                           |
| -------------------- | ------------------------- |
| **Python version**   | 3.8 or later              |
| **Package**          | `lumiid`                  |
| **Supported checks** | NIN, BVN, CAC, TIN, NUBAN |
| **Authentication**   | LumiID API key            |

***

### Overview

The LumiID Python SDK wraps the LumiID Identity Verification API. It provides consistent verification calls, typed errors, and advanced lookups where available.

#### One verification method

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

#### Typed exceptions

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

#### Advanced lookups

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

***

### Installation

Install from PyPI using pip:

```bash
python -m pip install lumiid
```

The SDK requires **Python 3.8 or later**. It installs `requests >= 2.28.0` automatically.

***

### Authentication

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

#### Environment variable

```python
import os
from lumiid import LumiID

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

{% hint style="warning" %}
Never commit API keys to version control. Store `LUMIID_API_KEY` in your environment or secret manager.
{% endhint %}

***

### Quick Start

Verify a NIN with this complete example:

```python
import os
from lumiid import LumiID

client = LumiID(api_key=os.environ["LUMIID_API_KEY"])

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

***

### NIN verification

Verify an 11-digit National Identification Number (NIN). NIN supports Basic and advanced lookups.

#### Basic verification

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

#### Advanced verification

```python
result = client.verify(id_type="NIN", id_number="12345678901", advance=True)
print(result)
```

***

### BVN verification

Verify an 11-digit Bank Verification Number (BVN). BVN supports Basic and advanced lookups.

#### Basic verification

```python
result = client.verify(id_type="BVN", id_number="12345678901")
print(result)
```

#### Advanced verification

```python
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, such as `RC1234567`.

#### Basic verification

```python
result = client.verify(id_type="CAC", id_number="RC1234567")
print(result)
```

#### Advanced verification

```python
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
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
result = client.verify(id_type="NUBAN", id_number="1234567890")
print(result)
```

***

### Handle errors

The SDK raises typed exceptions. Catch specific errors before the base `LumiIDError`.

```python
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:
    # Too many requests were sent
    print("Rate limit exceeded. Retry later.")

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      | Request rate limit 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             |

***

### Configure the client

Set the request timeout in seconds. The default is `30`.

```python
import os
from lumiid import LumiID

client = LumiID(
    api_key=os.environ["LUMIID_API_KEY"],
    timeout=60,
)
```

| Parameter | Type | Default  | Description                |
| --------- | ---- | -------- | -------------------------- |
| api\_key  | str  | required | Your LumiID API key        |
| timeout   | int  | 30       | Request timeout in seconds |

***

### Requirements

| Requirement | Version                                  |
| ----------- | ---------------------------------------- |
| Python      | 3.8 or later                             |
| `requests`  | 2.28.0 or later, installed automatically |

***

### Contribute to the SDK

Open an issue before proposing major changes. Then fork the repository and create a focused pull request.

```bash
# 1. Fork the repository, then clone your fork
git clone https://github.com/lumiid/lumiid-python.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
```

### Resources

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

### Python SDK FAQ

#### Which Nigerian identity checks does the SDK support?

Use the SDK for NIN, BVN, CAC, TIN, and NUBAN verification.

#### Which checks support advanced lookups?

NIN, BVN, and CAC support `advance=True`. TIN and NUBAN do not.

#### Should I expose my API key in client-side code?

No. Use the SDK from a trusted server environment. Store the key securely.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.lumiid.com/api-integration/sdks/lumiid-python-sdk-or-nigerian-identity-verification.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.