MTN Group Sim Management Service API

openapi: 3.2.0
info:
  title: Sim Management 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: SimManagementService
paths:
  /customers/registration:
    post:
      tags:
      - SimManagementService
      summary: provide the functionality of starter pack registration
      description: This operation facilitates the registration of new starter packs for customers, ensuring that all necessary details are captured and processed securely and efficiently for service activation.
      operationId: SimManagementService_post_registration_customersregistratio
      parameters:
      - name: registrationType
        in: query
        required: true
        schema:
          type: string
      - name: transactionId
        in: header
        required: false
        schema:
          type: string
      - name: x-country-code
        in: header
        required: false
        schema:
          type: string
      requestBody:
        content:
          application/json:
            schema:
              title: CustomerRegistrationRequest
              type: object
              properties:
                customerInformation:
                  type: array
                  items:
                    title: CustomerInformation
                    type: object
                    properties:
                      customerType:
                        type: string
                      engagedParty:
                        title: EngagedParty
                        type: object
                        properties:
                          contactMedium:
                            type: array
                            items:
                              title: ContactMedium
                              type: object
                              properties:
                                type:
                                  type: string
                                value:
                                  type: string
                          givenName:
                            type: string
                          middleName:
                            type: string
                          familyName:
                            type: string
                          individualIdentification:
                            type: array
                            items:
                              title: IndividualIdentification
                              type: object
                              properties:
                                placeOfIssue:
                                  type: string
                                issuingDate:
                                  type: string
                                expiryDate:
                                  type: string
                                visaExpiryDate:
                                  type: string
                                documentPurpose:
                                  type: string
                                type:
                                  type: string
                                identificationId:
                                  type: string
                          birthdate:
                            type: string
                          nationality:
                            type: string
                productOfferings:
                  type: array
                  items:
                    title: ProductOffering
                    type: object
                    properties:
                      characteristics:
                        type: array
                        items:
                          title: Characteristic
                          type: object
                          properties:
                            id:
                              type: string
                            name:
                              type: string
                            value:
                              type: string
                            type:
                              type: string
                      customFields:
                        title: CustomFields
                        type: object
                        properties:
                          registrationType:
                            type: string
        required: true
      responses:
        '200':
          description: Success
        '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
  /customers/sim/resourcePool:
    get:
      tags:
      - SimManagementService
      summary: Retrieve available Resources.
      description: This operation retrieves a pool of available resources, such as MSISDNs, allowing a customer who needs a new connection to select a desired number from the returned list based on their preferences.
      operationId: SimManagementService_get_availableMsisdn_customerssimresource
      parameters:
      - name: numberOfRec
        in: query
        required: false
        schema:
          type: integer
          format: int32
      - name: pattern
        in: query
        required: false
        schema:
          type: string
      - name: resourceType
        in: query
        required: false
        schema:
          type: string
      - name: transactionId
        in: header
        required: false
        schema:
          type: string
      - name: x-country-code
        in: header
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Success
        '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
  /customers/{customerId}/sim/resourcePool/reserve:
    post:
      tags:
      - SimManagementService
      summary: Reserve a resource such as an MSISDN
      description: Reserve a resource such as an MSISDN so that it cannot be retrieved in the operation for retrieving available resources (MSISDN's)
      operationId: SimManagementService_post_reserveResource_customerscustomerIds
      parameters:
      - name: customerId
        in: path
        required: true
        schema:
          type: string
      - name: transactionId
        in: header
        required: false
        schema:
          type: string
      - name: x-country-code
        in: header
        required: false
        schema:
          type: string
      requestBody:
        content:
          application/json:
            schema:
              title: ReserveResourceData
              type: object
              properties:
                numberOfRec:
                  type: integer
                  format: int32
                resources:
                  type: array
                  items:
                    title: Resource
                    type: object
                    properties:
                      id:
                        type: string
                      resourceType:
                        title: ResourceType
                        type: object
                        properties:
                          value:
                            type: string
                      value:
                        type: string
        required: true
      responses:
        '200':
          description: Success
        '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
  /customers/{customerId}/simRecycle/verifyStatus:
    get:
      tags:
      - SimManagementService
      summary: verify sim Recycle status
      description: This operation allows customers to verify the status of their SIM recycle request, providing a confirmation of whether the recycling process has been successfully completed or if it is still in progress.
      operationId: SimManagementService_get_simRecycleStatus_customerscustomerIds
      parameters:
      - name: customerId
        in: path
        required: true
        schema:
          type: string
      - name: senderId
        in: query
        required: true
        schema:
          type: string
      - name: transactionId
        in: header
        required: false
        schema:
          type: string
      responses:
        '200':
          description: Success
        '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
  /customers/{customerId}/simSwap:
    put:
      tags:
      - SimManagementService
      summary: Initiate the SIM swap process
      description: This operation initiates the SIM swap procedure for a customer, allowing them to transfer their existing mobile number to a new SIM card while maintaining their service.
      operationId: SimManagementService_put_initiateSimSwap_customerscustomerIds
      parameters:
      - name: customerId
        in: path
        required: true
        schema:
          type: string
      - name: targetSystem
        in: header
        required: false
        schema:
          type: string
      - name: transactionId
        in: header
        required: false
        schema:
          type: string
      - name: x-country-code
        in: header
        required: false
        schema:
          type: string
      requestBody:
        content:
          application/json:
            schema:
              title: InitiateSimSwapRequestDto
              type: object
              properties:
                nodeId:
                  type: string
                idNumber:
                  type: string
                dateOfBirth:
                  type: string
                relatedParty:
                  title: RelatedParty
                  type: object
                  properties:
                    id:
                      type: string
                    name:
                      type: string
                    role:
                      type: string
                    geographicLocation:
                      title: GeographicLocation
                      type: object
                      properties:
                        spatialRef:
                          type: string
                        geometry:
                          title: Geometry
                          type: object
                          properties:
                            x:
                              type: string
                            y:
                              type: string
                            z:
                              type: string
                    '@referredType':
                      type: string
                oldSimNumber:
                  type: string
                newMSISDN:
                  type: string
                newSimNumber:
                  type: string
                reasonCode:
                  type: string
                effectiveFrom:
                  type: string
                lastRechargeDate:
                  type: string
                  format: date-time
                lastRechargeAmount:
                  type: number
                  format: double
                simActivationDate:
                  type: string
                  format: date-time
                frequentlyDialedNumber:
                  type: string
                timestamp:
                  type: string
                mostRecentDeviceName:
                  type: string
                authenticationMethod:
                  type: string
        required: true
      responses:
        '200':
          description: Success
        '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
  /customers/{customerId}/simSwap/details:
    get:
      tags:
      - SimManagementService
      summary: Get sim details
      description: This operation retrieves detailed information about a customer's SIM card, including its current status, associated services, and other relevant technical specifications.
      operationId: SimManagementService_get_customerSimDetails_customerscustomerIds
      parameters:
      - name: customerId
        in: path
        required: true
        schema:
          type: string
      - name: targetSystem
        in: header
        required: false
        schema:
          type: string
      - name: transactionId
        in: header
        required: false
        schema:
          type: string
      - name: x-country-code
        in: header
        required: false
        schema:
          type: string
      responses:
        '200':
          description: Success
        '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
  /customers/{customerId}/simSwap/eligibility:
    get:
      tags:
      - SimManagementService
      summary: Get sim swap eligibility
      description: This operation determines if a customer is eligible for a SIM swap based on various criteria such as account status, identification, and regulatory requirements.
      operationId: SimManagementService_get_getSimSwapEligibility_customerscustomerIds
      parameters:
      - name: customerId
        in: path
        required: true
        schema:
          type: string
      - name: transactionId
        in: header
        required: false
        schema:
          type: string
      - name: x-country-code
        in: header
        required: false
        schema:
          type: string
      responses:
        '200':
          description: Success
        '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
  /customers/{customerId}/simSwap/nextAuthentication:
    post:
      tags:
      - SimManagementService
      summary: Get next Authentication (Q&A)
      description: This operation retrieves the next authentication question for a given customer, enabling a secure question-and-answer verification process during SIM swap requests.
      operationId: SimManagementService_post_getNextauthenticationQuestion_customerscustomerIds
      parameters:
      - name: customerId
        in: path
        required: true
        schema:
          type: string
      - name: transactionId
        in: header
        required: false
        schema:
          type: string
      requestBody:
        content:
          application/json:
            schema:
              title: GetNextAuthenticationQuestionRequestDto
              type: object
              properties:
                previousQuestionsAnswer:
                  title: PreviousQuestionsAnswer
                  type: object
                  properties:
                    questionKey:
                      type: string
                    answerKey:
                      type: string
        required: true
      responses:
        '200':
          description: Success
        '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
  /customers/{customerId}/simSwap/status:
    get:
      tags:
      - SimManagementService
      summary: Get sim swap status
      description: This operation allows customers to retrieve the current status of their SIM swap request, providing real-time updates on the progress and completion of the process.
      operationId: SimManagementService_get_getSimSwapStatus_customerscustomerIds
      parameters:
      - name: customerId
        in: path
        required: true
        schema:
          type: string
      - name: prefLang
        in: query
        required: false
        schema:
          type: string
      - name: requesterId
        in: query
        required: false
        schema:
          type: string
      - name: targetSystem
        in: header
        required: false
        schema:
          type: string
      - name: transactionId
        in: header
        required: false
        schema:
          type: string
      - name: xChanelId
        in: query
        required: false
        schema:
          type: string
      responses:
        '200':
          description: Success
        '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
  /customers/{customerId}/simSwap/validateStatus:
    get:
      tags:
      - SimManagementService
      summary: validate sim-swap status
      description: This operation validates the current status of a SIM swap request, ensuring all prerequisites are met and the process is proceeding as expected within the specified timeframe.
      operationId: SimManagementService_get_validateSimSwapStatus_customerscustomerIds
      parameters:
      - name: customerId
        in: path
        required: true
        schema:
          type: string
      - name: endDate
        in: query
        required: 

# --- truncated at 32 KB (38 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/mtn-group/refs/heads/main/openapi/mtn-group-simmanagementservice-api-openapi.yml