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.
openapi: 3.0.1
info:
title: Sim Management
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
- name: SimManagementService
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
/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."
# --- truncated at 32 KB (56 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/mtn-group/refs/heads/main/openapi/mtn-group-sim-management-staging.yml