MTN Group Number Recycle Service API

openapi: 3.2.0
info:
  title: Sim Management Number Recycle Service API
  description: This API provides a comprehensive suite of services for managing SIM-related operations, including SIM swap initiation, status tracking, eligibility checks, and resource management. It ensures secure and efficient handling of customer SIM lifecycle events.
  license:
    name: MADAPI
    url: https://developers.mtn.com/
  version: 3.0.0 - Last updated date:2026-07-15 18:20:11
servers:
- url: https://api.mtn.com/v1
  description: Production Server
security:
- OAuth2: []
tags:
- name: NumberRecycleService
paths:
  /customers/recycleStatus:
    post:
      tags:
      - NumberRecycleService
      summary: Retrieve Customer Registration Status by specifying the 'customerId'.
      description: This operation retrieves the current registration status of a customer based on their unique 'customerId', providing essential details about their service activation and account information.
      operationId: NumberRecycleService_post_customerSimRecycleStatus_customersrecycleStat
      parameters:
      - name: transactionId
        in: header
        required: false
        schema:
          type: string
      requestBody:
        content:
          application/json:
            schema:
              title: SimRecycleRequest
              required:
              - msisdn
              type: object
              properties:
                msisdn:
                  type: string
        required: true
      responses:
        '200':
          description: HTTP 200 indicating the request succeeded; the response body follows the documented schema for this operation and includes correlation identifiers where applicable for traceability across MTN MADAPI usage management flows.
          content:
            application/json:
              schema:
                title: SimRecycleResponse
                type: object
                properties:
                  data:
                    title: SimRecycleStatus
                    type: object
                    properties:
                      recycleStatus:
                        type: string
                      recycleDate:
                        type: string
                        format: date-time
                  transactionId:
                    type: string
                  statusCode:
                    type: string
                  supportMessage:
                    type: string
                  statusMessage:
                    type: string
                  customerId:
                    type: string
                  timestamp:
                    type: string
        '400':
          description: Bad request. Invalid request parameters, missing required fields, or validation errors.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/APIError'
        '401':
          description: Unauthorized. Invalid or missing authorization credentials, insufficient permissions, or authentication failure.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/APIError'
        '403':
          description: Forbidden. Access denied. The request is valid but the server refuses to perform it.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/APIError'
        '404':
          description: Not found. The requested resource was not found or does not exist.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/APIError'
        '500':
          description: Internal server error. Unexpected system failure, database connectivity issues, or external service integration problems.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/APIError'
        '502':
          description: Bad gateway. The server acting as a gateway received an invalid response from an upstream server.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/APIError'
        '503':
          description: Service unavailable. The server is temporarily unable to handle the request due to maintenance or overload.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/APIError'
      deprecated: false
components:
  schemas:
    APIError:
      title: APIError
      required:
      - statusCode
      - statusMessage
      type: object
      properties:
        statusCode:
          type: string
          description: Error status code
          example: '400'
        statusMessage:
          type: string
          description: Human-readable error message
          example: Bad request. Invalid parameters provided.
        supportMessage:
          type: string
          description: Technical support message or error code for troubleshooting
          example: VALIDATION_ERROR
        transactionId:
          type: string
          description: Transaction identifier for tracking and correlation
          example: '1234567890'
        sequenceNo:
          type: string
          description: Sequence number for request tracking
          example: '20250115120000001'
        timestamp:
          type: string
          description: Error timestamp in ISO 8601 format
          format: date-time
          example: 2025-01-15 12:00:00+00:00
        path:
          type: string
          description: API endpoint path where the error occurred
          example: /api/v1/resource
        method:
          type: string
          description: HTTP method of the request that caused the error
          example: POST
        downstreamStatusCode:
          type: string
          description: Downstream service error code if applicable
      description: Generic MADAPI error response structure
      example:
        statusCode: '400'
        statusMessage: Bad request. Invalid request parameters, missing required fields, or validation errors.
        supportMessage: API_ERROR
        transactionId: '1234567890'
        sequenceNo: '20250115120000001'
        timestamp: 2025-01-15 12:00:00+00:00
  securitySchemes:
    OAuth2:
      type: oauth2
      flows:
        clientCredentials:
          tokenUrl: https://api.mtn.com/v1/oauth/access_token
          scopes: {}
    Bearer:
      type: http
      description: Bearer token received from OAuth2.0 authentication with the MADAPI
      scheme: bearer
      bearerFormat: JWT