> 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/business-verification/tin-verification-api.md). # TIN Verification API The LumiID **TIN Verification API** enables businesses to validate tax identities for both **individuals** and **registered businesses**, helping reduce fraud, simplify compliance, and automate tax verification during customer and merchant onboarding. *** ## Overview | | | | --------------------- | ------------------------------------------------------------- | | **Country** | 🇳🇬 Nigeria | | **Data Sources** | Joint Tax Board (JTB) • Federal Inland Revenue Service (FIRS) | | **Verification Type** | Tax Identification Number (TIN) | | **Authentication** | API Key Required | | **Typical Latency** | < 2 seconds | | **Sandbox** | Supported | | **Compliance** | NDPR Ready | *** ## Endpoint **POST** ```http {{baseUrl}}/v1/ng/tin/ ``` *** ## Headers | Header | Description | | ------------- | ------------------------ | | Authorization | `Bearer YOUR_SECRET_KEY` | | Content-Type | `application/json` | *** ## Request Body | Field | Type | Required | Description | | ----- | ------ | -------- | ------------------------------------ | | `tin` | string | ✅ | Tax Identification Number to verify. | #### Example Request ```json { "tin":"12345678" } ``` *** ## Successful Response ```json { "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 ### Top-Level Response | Field | Type | Description | | ----------------- | ------- | ---------------------------------------------------------- | | `success` | boolean | Indicates whether the verification completed successfully. | | `code` | string | Machine-readable response code. | | `message` | string | Human-readable response message. | | `summary` | object | Verification summary. | | `data` | object | Verified tax registration record. | | `meta.request_id` | string | Unique request identifier for auditing and support. | | `meta.timestamp` | string | UTC response timestamp in ISO 8601 format. | *** ### `data` | Field | Type | Description | | --------------- | ------ | ------------------------------------------------- | | `tin` | string | Verified Tax Identification Number. | | `name` | string | Registered taxpayer or business name. | | `tax_office` | string | Assigned tax office. | | `business_type` | string | Taxpayer category such as `CORP` or `INDIVIDUAL`. | *** ## 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. | *** ## Security & Compliance * 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**. * Handle returned taxpayer information in accordance with the **Nigeria Data Protection Regulation (NDPR)** and applicable tax privacy requirements. *** ## Common Use Cases The TIN Verification API is commonly used for: * Business onboarding (KYB) * Vendor verification * Merchant onboarding * Tax compliance automation * Invoice and payment validation * Government procurement * Financial institutions * Enterprise compliance workflows *** ## Recommended Verification Flow For business onboarding and compliance, LumiID recommends the following workflow: 1. Verify the company's **CAC Registration Number**. 2. Verify the company's **Tax Identification Number (TIN)**. 3. Verify the business bank account using the **NUBAN Verification API**. 4. Continue onboarding after successful verification. This workflow helps ensure the legal identity, tax registration, and banking details of every business before activation. *** ## Example (Python) ```python 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()) ``` --- # 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/business-verification/tin-verification-api.md?ask=&goal= ``` `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.