Prerequisites

Before integrating with the TIRMS API, ensure the following requirements are in place:

Onboarding and Registration

  • Your organization must be registered and approved by the TIRMS system administrator.

API Key Generation

  • An administrator from your organization must log on to TIRMS to generate an API key.
  • Keep this key secure; it will be used in the Authorization header for every API request.

Webhook Setup (for phone number status update)

Note: This feature is available only to registered organizations using TIRMS.

If you want to receive notifications when a phone number previously verified by your organization undergoes a status change, we recommend setting up a webhook. Once configured, any status updates for numbers your organization has verified—such as a change from "BARRED" to "CHURNED"—will be automatically sent to the registered webhook URL. To set up a webhook for receiving updates on phone number statuses, please follow the steps below.

Steps:

  • On TIRMS, navigate to the API Integration page through the main navigation menu.
  • Locate and click the "Add a webhook" button to initiate the webhook creation process.
  • Specify the Webhook URL in the designated field (this is the secure endpoint where our system will send detailed event data and notifications).
  • From the available options, carefully select the specific Events that should trigger your webhook. You can choose multiple events to monitor different types of system activities.
  • Click "Add webhook" to finalize and activate your webhook configuration.

MSISDN Format Compliance

  • All phone numbers must be submitted in the 10, 11, or 13-digit MSISDN format (e.g., 8012345678, 08012345678, and 2348012345678), based on the E.164 standard, without the "+" symbol.

Network and Security Readiness

  • Ensure outbound HTTPS traffic is allowed from your system to the TIRMS API endpoints.
  • Use secure HTTPS (TLS) communication at all times.

Base URL

  • All endpoints must be accessed via the following base URL: Production: https://tirms.ncc.gov.ng/api/v1/phone/api

Upload Restrictions

  • The maximum size for the bulk of phone numbers and bulk updates is 100,000 records.

Development Team Familiarity

  • Your developers should be familiar with RESTful API principles, JSON payload structures, and handling common HTTP status codes.

Introduction

The Telecom Identity Risk Management System (TIRMS) API provides a centralized and secure interface for verifying and updating the status of mobile phone numbers across participating platforms. It supports fraud prevention, regulatory compliance, and the integrity of customer data.

User Categories

Telecom Operators – Authorized to update the status of phone numbers in the TIRMS database.

Service Providers (fintechs, banks, insurance companies) – Can verify phone number status for safe onboarding, authentication, or transactions.

Access Control

Status update endpoints → exclusive to telecom operators

Verification endpoints → available to all approved service providers

Quickstart

Authentication

All API calls require API Key-based authentication. The API key must be included in the Authorization header for every request.

Example Header:

Authorization: Bearer <API Key>

Glossary

  • MSISDN – Mobile Subscriber Integrated Services Digital Network Number
  • API Key – Security credential for authorization
  • Reassigned Date – Date number was officially reallocated
  • Churned – Number recycled
  • Swapped – SIM replaced (loss/theft/damage)
  • Blacklisted – Number blocked/barred
  • Null/Normal – Number not in churned/swapped/blacklisted states
  • Occurrence Date – Date the status occurred

API Endpoints

Telecom Operator Endpoints

Phone Number Status Update (Single) Endpoint

This endpoint allows authorized users to update the status of a single phone number in the system. It is typically used by telecom operators or designated entities to record changes such as churn, swap, blacklist, or reassignment events.

Method: PUT
URL: https://tirms.ncc.gov.ng/api/v1/phone/api/phone-numbers/status
Authentication: Bearer (API key)

When to Use:

  • After the phone number is churned
  • When a number is blacklisted due to fraudulent activity or regulatory actions
  • When a number is swapped

Phone Number Status Update Request Schema:

{
  "status": "BARRED",
  "phoneNumber": "07059316841",
  "reassignmentDate": "2025-09-15",
  "occurrenceOfStatusDate": "2025-09-15",
  "remarks": "Number reassigned to new user"
}

Phone Number Status Update Response Schema:

{
    "status": "Success",
    "data": {
        "phoneNumber": "07059316841",
        "status": "BARRED",
        "updateTimestamp": "2025-09-09 10:20:26",
        "remarks": "Number reassigned to new user"
    },
    "statusCode": "200"
}

Phone Number Status Update (Bulk) Endpoint

Allows authorized users to update the status of multiple phone numbers.

Purpose: This endpoint allows authorized operators (telecom providers or other designated entities) to update the status of multiple phone numbers at once in the TIRMS system. For example, suppose several numbers become churned, swapped, or blacklisted. In that case, the operator can submit those updates in bulk to ensure accurate and up-to-date records for downstream service providers.

Method: PUT
URL: https://tirms.ncc.gov.ng/api/v1/phone/api/phone-numbers/status/bulk
Authentication: Bearer (API key)

Request Format

The request body must be an array of objects, each representing a phone number update.

Request Fields

  • uid (string, required) → Unique identifier of the phone number (e.g., MSISDN or internal ID)
  • status (string, required) → Current status of the phone number. Allowed values:
    • CHURNED
    • SWAPPED
    • BLACKLISTED
    • NORMAL
  • reassignmentDate (string, optional) → Date the number was reassigned, format YYYY-MM-DD. Required if status = SWAPPED OR CHURNED
  • occurrenceOfStatusDate (string, required) → Date when the status became effective, format YYYY-MM-DD

Sample Request Payload:

[{
  "status": "CHURNED",
  "phoneNumber": "09012345678",
  "reassignmentDate": "2025-09-15",
  "occurrenceOfStatusDate": "2025-09-15",
  "remarks": "Number reassigned to new user"
},
{
  "status": "SWAPPED",
  "phoneNumber": "09098765432",
  "reassignmentDate": "2025-09-02",
  "occurrenceOfStatusDate": "2025-09-06",
  "remarks": "SIM card replaced due to damage"
}]

Sample Response:

{
  "status": "string",
  "data": {
    "message":"string",
    "link":"string"
  },
  "statusCode": "string"
}

Response Fields

  • status (string) → Overall outcome of the API call (success, failure)
  • data (string) → Additional message or details about the request handling (e.g., "Request accepted", "Invalid phone number format")
  • statusCode (string/integer) → HTTP status code returned by the API (200 for success, 400 for bad request, 500 for server error)

Bulk Phone Number Upload

Purpose: This endpoint allows telecom operators to seamlessly upload multiple phone numbers via API integration, enabling smooth interoperability with their legacy systems.

Method: POST
URL: https://tirms.ncc.gov.ng/api/v1/phone/api/phone-numbers/upload/bulk
Authentication: Bearer (API key)

Sample Request:

{
  "phoneNumbers": [
    {
      "phoneNumber": "08012345678",
      "reassignmentDate": "2025-06-15",
      "occurrenceOfStatusDate": "2025-06-01",
      "status": "REASSIGNED"
    },
    {
      "phoneNumber": "08123456789",
      "reassignmentDate": "2025-07-10",
      "occurrenceOfStatusDate": "2025-07-01",
      "status": "SWAPPED"
    },
    {
      "phoneNumber": "09098765432",
      "reassignmentDate": "2025-08-20",
      "occurrenceOfStatusDate": "2025-08-10",
      "status": "CHURNED"
    }
  ]
}

Sample Response:

{
  "status": "string",
  "data": {
    "message":"string",
    "link":"string"
  },
  "statusCode": "string"
}

Service Provider Endpoints (Fintechs, Banks, etc.)

Phone Number Status Verification Endpoint

Purpose: These endpoints are accessible to registered organizations for verifying the current status of phone numbers. Before a service provider onboards a user or allows them to perform sensitive operations—such as opening an account, initiating transactions, or resetting passwords—they should confirm that the phone number is both safe and currently owned by the user. This verification step helps detect cases where a number may have been recently churned, blacklisted, or swapped, thereby reducing the risk of fraud or unauthorized access.

Method: POST
URL: https://tirms.ncc.gov.ng/api/v1/phone/api/phone-numbers/verify
Authentication: Bearer (API key)

When to Use:

  • During user onboarding
  • Before initiating sensitive transactions
  • Periodic checks to ensure the ongoing validity of stored numbers

Sample Request:

{
  "phoneNumber": "07444009986"
}

Sample Response:

{
  "status": "Success",
  "data": {
    "status": "SWAPPED",
    "requestId": "ba0f41ee-d58d-44c3-9f18-04d7ecb804f9",
    "verificationStatus": "VERIFIED",
    "reassignmentDate": null,
    "verificationTimestamp": "2025-09-09 10:37:33",
    "occurrenceOfStatusDate": "2025-09-09",
    "mobileNetwork": "GLOBACOM",
    "msisdn": "07444009986",
    "errorMessage": null
  },
  "statusCode": "200"
}

Phone Number Status Verification (Bulk)

Purpose: This endpoint allows organizations—such as fintechs, banks, and other institutions—to verify multiple phone numbers at once within the TIRMS system. It is designed for seamless integration into legacy systems, enabling background verification of phone numbers without disrupting existing business processes.

Please note: Each request is limited to a maximum of 500 phone numbers.

Method: POST
URL: https://tirms.ncc.gov.ng/api/v1/phone/api/phone-numbers/verify/bulk
Authentication: Bearer (API key)

Sample Request Payload:

{   
  "phoneNumbers": [  
    "0801234578",  
    "28123456789",  
    "09087654321",  
    "07011223344",  
    "0912345670"  
  ]  
}

Sample Response:

{  
  "status": "string",  
  "data": [  
    {  
      "status": "BLACKLISTED, CHURNED, REASSIGNED, SWAPPED, NORMAL, NULL",  
      "requestId": "string",  
      "verificationStatus": "VERIFIED",
      "reassignmentDate": "2025-09-03",  
      "verificationTimestamp": "2025-09-03T16:02:32.767Z",  
      "occurrenceOfStatusDate": "2025-09-03",  
      "mobileNetwork": "string",  
      "msisdn": "string",
      "errorMessage": null
    }  
  ],  
  "statusCode": "string"  
}

Response Fields

  • status (string) → Overall outcome of the API call (success, failure)
  • data (array) → Contains verification details for one or more phone numbers
    • status (string) → Current status of the phone number. Possible values:
      • BLACKLISTED → The number is blocked due to fraud or compliance reasons
      • CHURNED → The number has been permanently disconnected
      • REASSIGNED → The number has been assigned to a new user
      • SWAPPED → The SIM associated with the number has been changed
      • NORMAL → The number is active and valid
      • NULL → No status could be determined
    • requestId (string) → Unique identifier for the verification request
    • verificationStatus (string) → The status of the phone number verification
      • VERIFIED - The number has been verified successfully
      • FAILED - The number is invalid
    • reassignmentDate (string, date) → Date when the number was reassigned (if applicable). Format: YYYY-MM-DD
    • verificationTimestamp (string, timestamp) → Exact date and time the verification was performed. Format: ISO 8601 (YYYY-MM-DDTHH:MM:SS.sssZ)
    • occurrenceOfStatusDate (string, date) → Date when the status event occurred (e.g., churn date, blacklist date). Format: YYYY-MM-DD
    • mobileNetwork (string) → The mobile network operator (e.g., "MTN", "Airtel", "Glo")
    • msisdn (string) → The phone number (MSISDN) being verified
    • errorMessage (string) → The error message for failed phone number verification
  • statusCode (string/integer) → HTTP status code returned by the API (200 for success, 400 for bad request, 404 for not found, etc.)

Error Handling

TIRMS uses standard HTTP status codes. Below are common responses:

  • 400 Bad Request: Missing or invalid parameter
  • 401 Unauthorized: Missing or invalid API Key
  • 403 Forbidden: Insufficient permission
  • 404 Not Found: Record not found
  • 429 Too Many Requests: Rate limit exceeded
  • 500 Internal Server Error: Unexpected error

Security Considerations

  • All API calls must be over HTTPS
  • Never expose API keys in frontend applications
  • Rotate keys regularly or immediately if compromised
  • Monitor logs for abuse

Frequently Asked Questions (FAQ)

  1. How do I get an API key?
    API keys can be generated from the TIRMS portal.

  2. Can I use the same API key across multiple services?
    Yes, but it's best practice to use separate keys for production, testing, and environments requiring different access levels.

  3. What phone number format should I use in requests?
    You should use the MSISDN format based on the E.164 standard (without the + symbol) for all phone numbers in your API requests. You can use 10, 11, or 13 digits.

  4. What does 'Null/Normal' mean in the verification response?
    Null/Normal indicates that the phone number does not fall under any defined status—such as churned, swapped, or blacklisted. It may also mean that the number has not yet been registered or updated in the TIRMS database.

  5. How frequently is the data updated?
    As frequently as possible.

  6. What happens if I try to update a number I'm not authorized to manage?
    If you attempt to update the status of a phone number that you are not authorized to manage, the system will reject the request and return an authorization error. Only registered telecom operators can update numbers within their allocated ranges. Unauthorized access attempts are logged and monitored for security and compliance purposes.

  7. Is batch verification supported?
    Yes, batch verification is supported via the Bulk Verification endpoint. Organizations can submit multiple phone numbers in a single request. While the API will acknowledge receipt of the request, the verification results for each number will be sent to the link in the response.

  8. What should I do when I hit the rate limit?
    If you hit the rate limit (429 error), wait before retrying.

  9. What if I send an invalid status in an update request?
    If your update request contains an invalid or missing status value, the system will reject the request and return a 400 Bad Request error. The response will include a clear message indicating the issue.