TIN Lookup Integration Guide

Overview

Our TIN Lookup service enables you to retrieve critical information associated with a Tax Identification Number (TIN). This guide will take you through the process of integrating this service into your application, allowing you to seamlessly access TIN-related details.

Prerequisites

To get started, please ensure to:

• Sign up on the Mono Dashboard.
• Create an App and fetch the generated Secret Key.

Integration Steps

Step 1: Make a TIN Lookup Request

To retrieve TIN-related information, send a POST request to the following endpoint:

POST https://api.withmono.com/v3/lookup/tin

Request Body Parameters

• number (required): Provide the Tax Identification Number (TIN) or the Corporate Affairs Commission (CAC) RC number for the lookup.
• channel (required): Specify the channel as "tin" or "cac".

Specifying Channels and Number

The TIN Lookup can be used to verify details of both individuals and businesses. For individuals, you only need can only pass tin in the channel field. However for businesses, you can either choose to pass the tin or cac in the channel field. When passing cac in channel, you must pass the rc-number in the number field

Include these two parameters in the request body to specify the TIN number and channel for the lookup.

Request Headers

Include the following header in your request for authentication:

• mono-sec-key (required): Your Mono secret key.

cURL Sample Request

curl -X POST \
  -H "Content-Type: application/json" \
  -H "mono-sec-key: YOUR_MONO_SECRET_KEY" \
  -d '{
    "number": "TIN_NUMBER", //RC_NUMBER
    "channel": "tin" // cac
  }' \
  https://api.withmono.com/v3/lookup/tin

Step 2 Process the Response

The response for both individual and business tin lookup request are similar. What diffrentiates one from the other is the tin_type returned in the response which can either be individual or corporate .

Sample response for BUSINESSES

If the TIN lookup request is successful for a business, you will receive the following response:

{
    "status": "successful",
    "message": "Lookup Successful",
    "timestamp": "2024-05-15T14:34:56.231Z",
    "data": {
        "taxpayer_name": "NOMO TECHNOLOGIES NIGERIA LIMITED",
        "cac_reg_number": "RC0000015",
        "firstin": "20000071-0001",
        "jittin": "1000800004",
        "tax_office": "LTO FINANCIAL SERVICES",
        "phone_number": "08012345678",
        "email": "hi@nomo.co",
        "tin_type": "CORPORATE"
    }
}

Sample response for INDIVIDUALS

If the TIN lookup request for an individual is successful, you will receive the following response:

{
    "status": "successful",
    "message": "Lookup Successful",
    "timestamp": "2024-05-15T14:38:52.908Z",
    "data": {
        "taxpayer_name": "SAMUEL OLAMIDE",
        "cac_reg_number": null,
        "firstin": null,
        "jittin": "1060000000",
        "tax_office": null,
        "phone_number": "09087654321",
        "email": "samuel@nomo.co",
        "tin_type": "INDIVIDUAL"
    }
}

The response includes essential TIN-related information such as email, name, organization number, phone number, registration number, tax office, TIN type, and more.