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

# TIN Verification API: Nigerian Tax Identification Number

> Verify Nigerian Tax Identification Numbers via JTB and FIRS. Validate individual and business tax identities for compliance, onboarding, and fraud checks.

Use the LumiID TIN Verification API to validate Nigerian Tax Identification Numbers for both individuals and registered businesses. The API queries official **Joint Tax Board (JTB)** and **Federal Inland Revenue Service (FIRS)** databases in real time, helping you reduce fraud, simplify compliance, and automate tax verification during customer and merchant onboarding.

## Overview

| Property | Value |
| - | - |
| **Country** | 🇳🇬 Nigeria |
| **Data Sources** | Joint Tax Board (JTB) · Federal Inland Revenue Service (FIRS) |
| **Verification Type** | Tax Identification Number (TIN) |
| **Typical Latency** | \< 2 seconds |
| **Sandbox** | Supported |
| **Compliance** | NDPR Ready |

***

## Endpoint

### `POST /v1/ng/tin/`

**Base URL:** `https://api.lumiid.com`

#### Headers

| Header | Value |
| - | - |
| `Authorization` | `Bearer YOUR_SECRET_KEY` |
| `Content-Type` | `application/json` |

#### Request body

**tin** `string` *required*

The Tax Identification Number to verify. Submit the TIN exactly as issued — do not include spaces or special characters.

**Example:** `12345678`

```json theme={null}
{
  "tin": "12345678"
}
```

***

## Success response

```json theme={null}
{
  "success": true,
  "code": "TIN_VERIFIED",
  "message": "TIN verification successful",
  "summary": {
    "verified": true,
    "verification_type": "TIN",
    "provider": "LumiID",
    "confidence_score": 1.0
  },
  "data": {
    "tin": "12345678",
    "name": "LUMIID TECH LTD",
    "tax_office": "MSTO LAGOS",
    "business_type": "CORP"
  },
  "meta": {
    "request_id": "req_a1b2c3d4e5",
    "timestamp": "2026-03-19T08:14:22.445821Z"
  }
}
```

***

## Response fields

**success** `boolean`

Indicates whether the verification completed successfully.

**code** `string`

Machine-readable response code (e.g. `TIN_VERIFIED`).

**message** `string`

Human-readable response message.

**summary** `object`

High-level verification summary.

**summary fields**

**verified** `boolean`

Whether the TIN was successfully verified.

**verification\_type** `string`

Always `TIN` for this endpoint.

**provider** `string`

Always `LumiID`.

**confidence\_score** `number`

Verification confidence on a scale of 0 to 1.

**data** `object`

The verified tax registration record.

**data fields**

**tin** `string`

The verified Tax Identification Number.

**name** `string`

Registered taxpayer or business name as held by the tax authority.

**tax\_office** `string`

The tax office assigned to this taxpayer.

**business\_type** `string`

Taxpayer category. Returns `CORP` for registered businesses or `INDIVIDUAL` for natural persons.

**meta** `object`

Request metadata.

**meta fields**

**request\_id** `string`

Unique request identifier for auditing and support.

**timestamp** `string`

UTC response timestamp in ISO 8601 format.

***

## Error codes

| HTTP | Code | Resolution |
| - | - | - |
| **400** | `INVALID_REQUEST` | Missing or invalid `tin` in the request body. |
| **400** | `TIN_VERIFICATION_FAILED` | Verification could not be completed. Verify the TIN and retry. |
| **401** | `INVALID_API_KEY` | Authentication failed. Verify your API credentials. |
| **401** | `UNAPPROVED_ORGANIZATION` | Complete organization approval before accessing Production APIs. |
| **401** | `SUBSCRIPTION_REQUIRED` | Enable the TIN Verification service in the LumiID Console. |
| **402** | `INSUFFICIENT_FUNDS` | Your LumiID wallet balance is too low. Top up before retrying. |
| **404** | `TIN_NOT_FOUND` | No matching tax record exists for the supplied TIN. |
| **500** | `SERVER_ERROR` | Unexpected internal error. Retry once or contact LumiID Support. |
| **503** | `SERVICE_UNAVAILABLE` | The tax verification service is temporarily unavailable. Retry after a short delay. |
| **504** | `TIMEOUT` | The verification request timed out. Retry with exponential backoff. |

***

## Recommended business onboarding flow

Follow this workflow to fully verify a business's legal identity, tax registration, and banking details before activation.

**1. Verify CAC Registration Number**

Call the [CAC Business Verification API](https://docs.lumiid.com/api-reference/cac-verification) to confirm the company is registered and active with the Corporate Affairs Commission.

**2. Verify the TIN**

Call `POST /v1/ng/tin/` to confirm the company holds a valid Tax Identification Number and that the registered name matches your records.

**3. Verify the business bank account via NUBAN API**

Use the NUBAN Verification API to confirm the bank account belongs to the same legal entity before disbursing funds or activating payouts.

**4. Continue onboarding**

After all checks pass, activate the business account with a complete audit trail covering registration, tax identity, and banking verification.

> [!NOTE]
>
> This workflow ensures the legal identity, tax registration, and banking details of every business are validated before activation.

***

## Code example

```python Python theme={null}
import requests

url = "https://api.lumiid.com/v1/ng/tin/"

headers = {
    "Authorization": "Bearer YOUR_SECRET_KEY",
    "Content-Type": "application/json"
}

payload = {
    "tin": "12345678"
}

response = requests.post(
    url,
    json=payload,
    headers=headers
)

print(response.json())
```

***

## Security and compliance

> [!WARNING]
>
> Handle all returned taxpayer information in accordance with the **Nigeria Data Protection Regulation (NDPR)** and applicable tax privacy requirements. Do not store or share TIN data beyond your stated compliance purpose.

* Tax records are retrieved directly from official **Joint Tax Board (JTB)** and **Federal Inland Revenue Service (FIRS)** databases.
* All API requests must be made over **HTTPS**.
* Every successful verification includes a unique `request_id` for auditing and troubleshooting.
* Each successful verification consumes **one wallet credit** from your LumiID account.
* Process returned taxpayer information in line with the **Nigeria Data Protection Act (NDPA)** and your organization's data handling policies.


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