MTN Group Customers API

openapi: 3.2.0
info:
  title: Mtn Group Customers API
  version: '1.0'
  description: 'Operations tagged Customers across 6 of this provider''s published API definitions: mtn-group-loans-v2.yml, mtn-group-mtn-customer-locations-api-v1.yml, mtn-group-mtn-customer-plans-api-v2.yml, mtn-group-mtn-customer-profiles-api-v2-product.yml, mtn-group-mtn-customer-score.yml, mtn-group-mtn-subscription-api-v2.yml. Each path carries the servers of the definition it was published in.'
servers:
- url: https://api.mtn.com/v2
- url: https://api.mtn.com/v1
tags:
- name: Customers
paths:
  /customers/{customerId}/loans/advance:
    post:
      tags:
      - Customers
      summary: Gets a loan advance.
      description: Get a loan advance for an MTN customer.
      operationId: getLoanAdvance
      parameters:
      - name: customerId
        in: path
        description: ID of the customer. It could be MSISDN, email address, or any other customer identifier
        required: true
        schema:
          type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/LoanAdvanceResponse'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      deprecated: false
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/LoanProvisioningDetails'
        required: true
    servers:
    - url: https://api.mtn.com/v2
  /customers/{customerId}/loans/advance/status:
    get:
      tags:
      - Customers
      summary: Gets loan advance status.
      description: Get a loan advance status for an MTN customer.
      operationId: getLoanAdvanceStatus
      parameters:
      - name: customerId
        in: path
        description: ID of the customer. It could be MSISDN, email address, or any other customer identifier
        required: true
        schema:
          type: string
      - name: transactionId
        in: header
        description: The transaction Id used in making the loan advance request
        required: true
        schema:
          type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/LoanStatusResponse'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      deprecated: false
    servers:
    - url: https://api.mtn.com/v2
  /customers/{customerId}/loans/eligibleBundle:
    get:
      tags:
      - Customers
      summary: Retrieves the list of eligible loan.
      description: Retrieves loan eligibility status of an MTN customer.
      operationId: checkLoanEligibility
      parameters:
      - name: customerId
        in: path
        description: ID of the customer. It could be MSISDN, email address, or any other customer identifier
        required: true
        schema:
          type: string
      - name: type
        in: query
        required: false
        description: Specify the type of eligibility to check for. Returns all if none is specified.
        schema:
          type: string
          enum:
          - AIRTIME
          - DATA
          - VOICE
          - SMS
          - ALL
          default: ALL
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EligibilityResponse'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      deprecated: false
    servers:
    - url: https://api.mtn.com/v2
  /customers/{customerId}/locations:
    get:
      description: Retrieves the Location details of an MTN customer
      summary: View customer locations
      operationId: Retrieves the Location details of an MTN customer
      tags:
      - Customers
      parameters:
      - name: customerId
        in: path
        description: ID of the customer. It could be MSISDN, email address, or any other customer identifier. if id is msisdn, format must be E.123
        required: true
        schema:
          type: string
      responses:
        200:
          description: Customer Locations object. For a successful request, the response will contain all the customers details. If the customer does not have any requested data, then those fields will be null. E.g. if the customer does not any location set, then Country and Operator will be null.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CustomerLocations'
        400:
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorDefault'
        401:
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorDefault'
        403:
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorDefault'
        404:
          description: Customer not found
          content:
            The data object/envelope will be null:
              example:
                data: null
        405:
          description: Method Not allowed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error_2'
        500:
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error_2'
      security:
      - ApiKeyAuth: []
    servers:
    - url: https://api.mtn.com/v1
  /customers/{id}/plans/FRI:
    get:
      tags:
      - Customers
      summary: Retrieves a customers FRI
      description: Retrieves FRI for MTN customer.
      operationId: getFRIUsingPOST
      parameters:
      - name: id
        in: path
        description: id
        required: true
        schema:
          type: string
      - name: targetSystem
        in: header
        description: Target System
        required: true
        schema:
          type: string
      - name: transactionId
        in: header
        description: transactionId
        required: true
        schema:
          type: string
      - name: x-country-code
        in: header
        description: x-country-code
        required: true
        schema:
          type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetFRIResponse'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error_3'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error_3'
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error_3'
        '404':
          description: Customer not found
          content:
            The data object/envelope will be null:
              example:
                data: null
        '405':
          description: Method Not allowed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error_3'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error_3'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/GetFRIRequest'
        description: Financial Resource Information
        required: true
      security:
      - ApiKeyAuth: []
      - OAuth2: []
    servers:
    - url: https://api.mtn.com/v2
  /customers/{id}/plans/FRI/state:
    patch:
      tags:
      - Customers
      summary: Block and Unblock operations are initiated on Customer FRI
      description: By Interpreting value for 'state' MADAPI initiates   Block and Unblock requests on Customer FRI
      operationId: UpdateFRIUsingPATCH
      parameters:
      - name: id
        in: path
        description: ID of the customer. It could be MSISDN, email etc. combination of id and idType defines accountHolderId which will be sent to ECW System as identity
        required: true
        schema:
          type: string
      - name: idType
        in: header
        description: idtype defines the identification type being sent by the 3pp like MSISDN, customer id etc
        schema:
          type: string
          enum:
          - MSISDN
      - name: targetSystem
        in: header
        description: Target System is the backend to which MADAPI Sends th request
        required: true
        schema:
          type: string
      - name: transactionId
        in: header
        description: transactionId is unique identifier for every request, it is sent by source system like SAS to MADAPI
        schema:
          type: string
      - name: x-origin-channelId
        in: header
        description: Source System Details like SAS etc
        schema:
          type: string
      - name: x-authorization
        in: header
        description: Encrypted ECW credentials
        required: true
        schema:
          type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UpdateFRIResponse'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error_3'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error_3'
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error_3'
        '404':
          description: Customer not found
          content:
            The data object/envelope will be null:
              example:
                data: null
        '405':
          description: Method Not allowed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error_3'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error_3'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateFRIRequest'
        description: Financial Resource Identifier
        required: true
      security:
      - ApiKeyAuth: []
      - OAuth2: []
    servers:
    - url: https://api.mtn.com/v2
  /customers/{customerId}/plans:
    get:
      description: Retrieves the Billing Plan and related details of an MTN customer.
      summary: View customer plans
      tags:
      - Customers
      parameters:
      - name: customerId
        in: path
        description: ID of the customer. It could be MSISDN, email address, or any other customer identifier. if id is msisdn, format must be Eg.123
        required: true
        schema:
          type: string
      - name: fixedLine
        in: query
        description: Fixed line whose balances is fetched
        required: false
        schema:
          type: string
      - name: plan
        in: query
        description: Plan type to filter list of balances
        required: false
        schema:
          type: string
          enum:
          - VOICE
          - DATA
          - SMS
      - name: momo
        in: query
        description: Indicates whether to query balances for a MoMo Customer
        required: false
        schema:
          type: boolean
      - name: includeReservations
        in: query
        description: Indicates whether reservations should be included in the response. This parameter goes hand in hand with the momo query parameter and will have no use if supplied when momo is not true. Default is false.
        required: false
        schema:
          type: boolean
      - name: referenceid
        in: query
        description: This is required to handle the correlation between the 2 systems
        required: false
        schema:
          type: string
      - name: quoteid
        in: query
        description: Indicates whether a corresponding quote should be considered. This parameter goes hand-in-hand with the momo query parameter and will have no use if supplied when momo is not true.
        required: false
        schema:
          type: string
      - name: targetSystem
        in: query
        description: Name of the backend system
        x-example: EWP
        schema:
          type: string
      - name: segment
        in: query
        required: false
        description: This is the type of customer doing the transaction. This can be  agent, admin , merchant or subscriber
        schema:
          type: string
          enum:
          - subscriber
          - admin
          - agent
          - merchant
      - name: idType
        in: query
        required: false
        description: Type of the customerId in the path.
        schema:
          type: string
          enum:
          - MSISDN
          - USER
      - in: query
        name: prefLanguage
        required: false
        description: The language in which the response is required
        schema:
          type: string
          enum:
          - En
          - Fr
      - in: query
        name: amount
        required: false
        description: The threshold amount against which the actual balance will be compared
        schema:
          type: integer
      - name: transactionId
        in: header
        description: unique ID generated for each transaction
        required: false
        schema:
          type: string
      - name: usageType
        in: query
        required: false
        description: Type of usage to be fetched. 1 – All, 2 – Active, 3 – Inactive
        schema:
          type: number
          enum:
          - 1
          - 2
          - 3
      - name: extRequest
        in: query
        required: false
        description: Define if the request is external or not.
        schema:
          type: string
          enum:
          - true
          - false
      responses:
        '200':
          description: Customer Plans object. For a successful request, the response will contain all the customers details. If the customer does not have any requested data, then those fields will be null. E.g. if the customer does not have a startDate set, then it will be null. If the customer does not have any Balance set, then the Balance array will be null.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CustomerPlans'
        '207':
          description: If there was an error retrieving some part of the request, then the successful request will be shown, and the remaining failed objects will be be excluded. E.g. if there was an error retrieving Balance information, then the balance object will be empty
          content:
            Partially Successfuls Response, showing valid plan data, but balance object is null:
              example:
                data:
                  type: Postpaid
                  status: Active
                  startDate: '2019-04-12T14:31:21.810Z'
                  endDate: '2021-04-12T14:31:21.810Z'
                  language: '1'
                  balance: null
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error_3'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error_3'
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error_3'
        '404':
          description: Customer not found
          content:
            The data object/envelope will be null:
              example:
                data: null
        '405':
          description: Method Not allowed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error_3'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error_3'
      security:
      - ApiKeyAuth: []
      - OAuth2: []
    patch:
      tags:
      - Customers
      summary: Tariff plan migration
      description: Migrate the customer from one tariff plan to another
      operationId: trariffMigration
      security:
      - ApiKeyAuth: []
      parameters:
      - name: customerId
        in: path
        description: ID of the customer. It could be MSISDN, email address, or any other customer identifier. if id is msisdn, format must be E.123
        required: true
        schema:
          type: string
      - name: transactionId
        in: header
        description: Client generated unique Id to include for tracing requests
        required: false
        schema:
          type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  statusCode:
                    type: string
                    description: HTTP error code extension
                    example: '0000'
                  statusMessage:
                    type: string
                    example: Success
                  sequenceNo:
                    type: string
                    description: A unique identifier for tracking all requests
                    example: '1239848898'
                  data:
                    type: object
                    properties:
                      responseType:
                        example: PRODUCT
                      action:
                        example: PRODUCT_BUY
                      planId:
                        example: NACT_NG_others_2
                      productId:
                        example: '2'
                      productName:
                        example: Change Plan
                      productType:
                        example: others
                      amount:
                        type: string
                        description: The whole units of the amount.
                        example: '100'
                      country:
                        type: string
                        example: NG
                      notification:
                        type: string
                        example: You are successfully migrated to xyz paln.
                  _link:
                    type: object
                    properties:
                      self:
                        type: object
                        properties:
                          href:
                            type: string
                            example: https://api.mtn.com/v1/customers/2348064816493/plans/trariff
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error_3'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error_3'
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error_3'
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error_3'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error_3'
        '503':
          description: Service Unavailable
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error_3'
        '999':
          description: Unknown Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error_3'
      requestBody:
        content:
          application/json:
            schema:
              type: object
              required:
              - planId
              properties:
                planId:
                  type: string
                  example: NACT_NG_others_2
                providerId:
                  type: string
                  enum:
                  - CIS
                  description: Target system meant to process the request
        required: true
    servers:
    - url: https://api.mtn.com/v2
  /customers/{customerId}/plans/{productCode}:
    get:
      description: Retrieves plans for product
      summary: View customer plans for product
      tags:
      - Customers
      security:
      - ApiKeyAuth: []
      parameters:
      - name: customerId
        in: path
        description: ID of the customer. It could be MSISDN, email address, or any other customer identifier. if id is msisdn, format must be E.123
        required: true
        schema:
          type: string
      - name: productCode
        in: path
        description: Product code for data package
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Customer Plans object. For a successful request, the response will contain all the plans details. If the customer does not have any requested data, then those fields will be null. E.g. if the customer does not have a startDate set, then it will be null. If the customer does not have any Balance set, then the Balance array will be null.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CustomerPlans'
        '207':
          description: If there was an error retrieving some part of the request, then the successful request will be shown, and the remaining failed objects will be be excluded. E.g. if there was an error retrieving Balance information, then the balance object will be empty
          content:
            Partially Successfuls Response, showing valid plan data, but balance object is null:
              example:
                data:
                  type: Postpaid
                  status: Active
                  startDate: '2019-04-12T14:31:21.810Z'
                  endDate: '2021-04-12T14:31:21.810Z'
                  language: '1'
                  balance: null
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error_3'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error_3'
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error_3'
    servers:
    - url: https://api.mtn.com/v2
  /customers/{customerId}/plans/refill:
    patch:
      tags:
      - Customers
      summary: Airtime Refill
      description: Will be used by 3rd-party partners (3PP) for airtime recharge of a prepaid subscriber
      operationId: refillAccount
      security:
      - ApiKeyAuth: []
      parameters:
      - name: customerId
        in: path
        description: ID of the customer. It could be MSISDN, email address, or any other customer identifier. if id is msisdn, format must be E.123
        required: true
        schema:
          type: string
      - name: transactionId
        in: header
        description: Client generated unique Id to include for tracing requests
        required: false
        schema:
          type: string
      - name: sourceSystemId
        in: header
        description: Source system Id to include for tracing requests
        required: false
        schema:
          type: string
      - name: channel
        in: header
        schema:
          type: string
          enum:
          - MyMTNApp
          - MOD
      - name: partnerName
        in: header
        description: Partner Name
        schema:
          type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  statusCode:
                    type: string
                    description: HTTP error code extension
                  statusMessage:
                    type: string
                  sequenceNo:
                    type: string
                    description: A unique identifier for tracking all requests
                    example: '1239948893'
                  data:
                    type: object
                    properties:
                      amount:
                        type: string
                        description: The whole units of the amount. For example if currency is NGN, then 100 unit is
                      currencyCode:
                        type: string
                        description: The 3-letter currency code defined in ISO 4217.
                      serialStatus:
                        type: string
                        description: Status of the voucher being loaded
                      actionStatus:
                        type: string
                        description: Status of the action being taken
                      status:
                        type: string
                        description: Status of the refill
                      addtionalInformation:
                        type: object
                        properties:
                          name:
                            type: string
                            description: Additional information name
                          description:
                            type: string
                            description: Description of the additional information
                  _link:
                    type: object
                    properties:
                      self:
                        type: object
                        properties:
                          href:
                            type: string
                            example: https://api.mtn.com/v1/customers/2348064816493/refill
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error_3'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error_3'
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error_3'
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error_3'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error_3'
        '503':
          description: Service Unavailable
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error_3'
        '999':
          description: Unknown Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error_3'
      requestBody:
        content:
          application/json:
            schema:
              type: object
              required:
              - refillType
              properties:
                refillType:
                  type: string
                  description: Specify the refill type
                  enum:
                  - voucher
                  - voucherless
                voucherActivationCode:
                  type: string
                  description: Voucher Activation Code, Required if refillType is Voucher Base.
                refillProfileId:
                  type: string
                  description: Refill Profile ID, Required if refillType is Voucherless.
                transactionAmount:
                  type: string
                  description: Required if refillType is Voucherless
                targetSystem:
                  type: string
                  description: Backend system expected to fulfil the request
                  enum:
                  - PPMS
                  - AIR
                serialNumber:
                  type: string
                  description: Serial number of the voucher incase the refill is voucher
        required: true
    servers:
    - url: https://api.mtn.com/v2
  /customers/{id}/plans/provision:
    post:
      tags:
      - Customers
      summary: Provision the customer and return customer details along with MSISDN
      description: Provision the customer and returns customer details along with MSISDN with SIM number as input.
      operationId: getCustomerDetails
      parameters:
      - name: id
        in: path
        description: This could be either MSISDN or Serial number of the SIM of the customer for who the provision request is raised.
        required: true
        schema:
          type: string
      - name: transactionId
        in: header
        description: Unique ID for the transaction.
        required: true
        schema:
          type: string
      - name: sourceIdentifier
        in: query
        description: This field denotes the channel that is initiating request to SOA., ex-'Online, USSD, MyMTNApp, Payjoy'
        required: false
        schema:
          type: string
      - name: idType
        in: query
        description: Mention the type of id- MSISDN or Serial number of the SIM.
        required: true
        schema:
          type: string
          enum:
          - MSISDN
          - SerialNumber
      responses:
        '200':
          description: IBF Provision Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/provisionResponse'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
   

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