MTN Group Customer API

openapi: 3.2.0
info:
  title: Mtn Group Customer API
  version: '1.0'
  description: 'Operations tagged Customer across 5 of this provider''s published API definitions: mtn-group-customer-survey.yml, mtn-group-mtn-customer-kyc-api-v1-product.yml, mtn-group-mtn-nigeria-customer-datashare.yml, mtn-group-mtn-nigeria-data-gifting-v1.yml, mtn-group-tmf629-customer-management.yml. Each path carries the servers of the definition it was published in.'
servers:
- url: https://api.mtn.com/v1/survey
- url: https://api.mtn.com/v1/customers
- url: https://api.mtn.com/v1/datashare
- url: https://api.mtn.com/v1/datagifting
- url: https://serverRoot/tmf-api/customerManagement/v4/
tags:
- name: Customer
paths:
  /customers/{customerId}:
    get:
      tags:
      - Customer
      summary: Get Survey Quetions
      description: Fetch Survey Questions and Options.
      parameters:
      - name: customerId
        in: path
        description: Source Msisdn. The format must be E.123
        required: true
        schema:
          type: string
      - name: surveyId
        in: query
        required: false
        description: The unique ID of a particular survey
        schema:
          type: string
      - name: targetSystem
        in: query
        schema:
          type: string
          enum:
          - CLM
          - DIGISURVEY
          - CLM_REST
      - name: surveyType
        in: query
        schema:
          type: string
          enum:
          - eValidator
          - SHARENSELL
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                type: object
                properties:
                  statusCode:
                    type: string
                    description: This is the MADAPI Canonical response Code (it is 4 characters long and it is not the HTTP Status Code which is 3 characters long). Back-end system response are mapped to specific canonical response codes which are returned. More information on these mappings can be found on the MADAPI Confluence Page 'Response Codes'
                  statusMessage:
                    type: string
                    description: Status Message
                  transactionId:
                    type: string
                    description: API generated Id to include for tracing requests
                  data:
                    $ref: '#/components/schemas/DataResponse'
                  _links:
                    type: object
                    properties:
                      self:
                        type: string
                        example: https://api.mtn.com/v1/survey/customers/23464618463
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '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'
        '405':
          description: Method No Allowed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '406':
          description: Not acceptable
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '415':
          description: Unsupported media Type
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      security:
      - ApiKeyAuth: []
    post:
      tags:
      - Customer
      summary: Submit Survey and more KYC Answers
      description: Submit a list of questions and answers to survey.
      parameters:
      - name: surveyId
        in: header
        description: unique ID generated for each transaction
        required: false
        schema:
          type: string
      - name: surveyType
        in: header
        description: Survey type
        required: false
        schema:
          type: string
      - name: countryCode
        in: header
        description: Survey type
        required: false
        schema:
          type: string
      - name: customerId
        in: path
        description: Source Msisdn. The format must be E.123
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Success Response
          content:
            application/json:
              schema:
                type: object
                properties:
                  statusCode:
                    type: string
                    description: This is the MADAPI Canonical response Code (it is 4 characters long and it is not the HTTP Status Code which is 3 characters long). Back-end system response are mapped to specific canonical response codes which are returned. More information on these mappings can be found on the MADAPI Confluence Page 'Response Codes'
                  statusMessage:
                    type: string
                    description: Status Message
                  transactionId:
                    type: string
                    description: API generated Id to include for tracing requests
                  data:
                    $ref: '#/components/schemas/DataResponse'
                  _links:
                    type: object
                    properties:
                      self:
                        type: string
                        example: https://api.mtn.com/v1/survey/customers/23464618463
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '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'
        '405':
          description: Method No Allowed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '406':
          description: Not acceptable
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '415':
          description: Unsupported media Type
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      requestBody:
        content:
          application/json:
            schema:
              type: object
              required:
              - answers
              properties:
                hash:
                  type: string
                  example: Wk68gjJxucqM4qxTYCNH94TMid0KhIaE
                  description: The unique hash identifier for submiting a survey answer
                targetSystem:
                  type: string
                  example: DIGISURVEY
                  enum:
                  - CLM
                  - DIGISURVEY
                  - CLM_REST
                  - GENESIS
                surveyType:
                  type: string
                  enum:
                  - SHARENSELL
                  - eValidator
                servicePlan:
                  type: string
                  description: This is the service class of the customerId submiting survey answers
                answers:
                  type: array
                  description: The list of answered questions
                  items:
                    type: object
                    properties:
                      id:
                        type: integer
                      message:
                        type: string
                      input:
                        type: string
        required: true
      security:
      - ApiKeyAuth: []
    servers:
    - url: https://api.mtn.com/v1/survey
  /customers/surveyOptInByTimeStamp:
    get:
      tags:
      - Customer
      summary: Get Survey Msisdn List in CSV format
      description: Fetch Survey Msisdn List in CSV format.
      parameters:
      - name: startDate
        in: query
        schema:
          type: string
      - name: endDate
        in: query
        description: startDate
        required: true
        schema:
          type: string
      - name: targetSystem
        in: query
        schema:
          type: string
          enum:
          - GENESIS
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                type: object
                properties:
                  statusCode:
                    type: string
                    description: This is the MADAPI Canonical response Code (it is 4 characters long and it is not the HTTP Status Code which is 3 characters long). Back-end system response are mapped to specific canonical response codes which are returned. More information on these mappings can be found on the MADAPI Confluence Page 'Response Codes'
                  statusMessage:
                    type: string
                    description: Status Message
                  transactionId:
                    type: string
                    description: API generated Id to include for tracing requests
                  data:
                    $ref: '#/components/schemas/SurveyListResponse'
                  _links:
                    type: object
                    properties:
                      self:
                        type: string
                        example: https://api.mtn.com/v1/survey/customers/surveyOptInByTimeStamp
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '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'
        '405':
          description: Method No Allowed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '406':
          description: Not acceptable
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '415':
          description: Unsupported media Type
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      security:
      - ApiKeyAuth: []
    servers:
    - url: https://api.mtn.com/v1/survey
  /customers/surveyInvitation:
    post:
      tags:
      - Customer
      summary: Submit Survey and more KYC Answers
      description: Submit a list of questions and answers to survey.
      parameters:
      - name: transactionId
        in: header
        description: Transaction Id for tracking purposes
        required: false
        schema:
          type: string
      responses:
        '200':
          description: Identity status response from ROC Enroll
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/surveyInvitationResponse'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error400'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error401'
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error404'
        '405':
          description: Method No Allowed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error405'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error500'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/surveyInvitationRequest'
        required: true
      security:
      - ApiKeyAuth: []
    servers:
    - url: https://api.mtn.com/v1/survey
  /customers/{customerId}/kyc:
    parameters:
    - name: customerId
      in: path
      description: ID of the customer. It could be MSISDN, email address, or any other customer identifier. if customerId is msisdn, then the format must be E.123
      required: true
      schema:
        type: string
    - name: startDate
      in: query
      description: An optional parameter, together with endDate, allows developers to specify a time range by which to query customer data on. If you want to request data for 2 months, then start date will need to be set to 2 months prior to today, and endDate to todays date. If this is not set, the date range will be defaulted to 6 months
      example: '20190329'
      schema:
        type: string
        format: date
    - name: endDate
      in: query
      description: An optional parameter, together with endDate, allows developers to specify a time range by which to query customer data on. If you want to request data for 2 months, then start date will need to be set to 2 months prior to today, and endDate to todays date. If this is not set, the date range will be defaulted to 6 months
      example: '20190929'
      schema:
        type: string
        format: date
    - name: transactionId
      in: header
      description: Client generated Id to include for tracing requests, so that the API can easily trace the HTTP request all the way from a client to MTNs backend processes (via our proxies). Each time a request is made to an MTN API the client should include a unique request reference in the HTTP Header. The value must be between 5 and 20 characters, and consist of ASCII letters, digits, or the characters +, /, =, and -. Invalid or blank IDs will be ignored and replaced with generated ones. MTN may use this to detect duplicate transactions from the client, but this functionality is not always guaranteed, so clients must make their own efforts to prevent duplicate transactions. MTN will also log the transactionId in order to assist with debugging and to correlate transactions processed by the API to requests from the client.
      schema:
        type: string
    get:
      summary: Retrieve customer KYC data
      tags:
      - Customer
      responses:
        200:
          description: OK
          content:
            application/json:
              schema:
                description: Customer Object
                $ref: '#/components/schemas/kyc'
        400:
          description: Bad Request. A Bad Request response is returned when the path info doesn't have the right format, or a parameter or request body value doesn't have the right format, or a required parameter is missing, or values have the right format but are invalid in some way. The client SHOULD NOT repeat the request without modifications.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error_2'
        401:
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error_2'
        403:
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error_2'
        404:
          description: Customer not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error_2'
        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'
    servers:
    - url: https://api.mtn.com/v1/customers
  /customers/{senderMsisdn}:
    post:
      tags:
      - Customer
      summary: Share Data
      description: Provides the ability to share data with customer.
      parameters:
      - name: senderMsisdn
        in: path
        description: Source Msisdn. The format must be E.123
        required: true
        schema:
          type: string
      - name: productcode
        in: query
        required: true
        description: The product code e.g NACT_NG_others_1
        schema:
          type: string
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DataShareResponse'
        '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'
        '405':
          description: Method No Allowed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error_3'
        '406':
          description: Not acceptable
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error_3'
        '415':
          description: Unsupported media Type
          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/ReceiverInformation'
        description: Request body
        required: true
      security:
      - ApiKeyAuth: []
    get:
      deprecated: true
      tags:
      - Customer
      summary: Retrieve Receivers' MSISDN
      description: Provides the ability to retrieve all registered receiver's msisdn.
      parameters:
      - name: senderMsisdn
        in: path
        description: Source Msisdn. The format must be E.123
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DataShareListResponse'
        '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'
        '405':
          description: Method No Allowed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error_3'
        '406':
          description: Not acceptable
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error_3'
        '415':
          description: Unsupported media Type
          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: []
    patch:
      deprecated: true
      tags:
      - Customer
      summary: Update Receiver's information
      description: Provides the ability to update the receiver's msisdn and sharable data amount.
      parameters:
      - name: senderMsisdn
        in: path
        description: Source Msisdn. The format must be E.123
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessResponse'
        '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'
        '405':
          description: Method No Allowed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error_3'
        '406':
          description: Not acceptable
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error_3'
        '415':
          description: Unsupported media Type
          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/ReceiverInformation'
        description: Request body
        required: true
      security:
      - ApiKeyAuth: []
    delete:
      deprecated: true
      tags:
      - Customer
      summary: Remove Receiver's Msisdn
      description: Provides the ability for removing receiver's msisdn.
      parameters:
      - name: senderMsisdn
        in: path
        description: Source Msisdn. The format must be E.123
        required: true
        schema:
          type: string
      - name: receiverMsisdn
        in: query
        description: The beneficiary msisdn. The format must be E.123
        schema:
          type: string
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessResponse'
        '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'
        '405':
          description: Method No Allowed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error_3'
        '406':
          description: Not acceptable
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error_3'
        '415':
          description: Unsupported media Type
          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: []
    servers:
    - url: https://api.mtn.com/v1/datashare
  /customers/{customerId}/analytics:
    get:
      tags:
      - Customer
      summary: Get analytic information of your data usage
      description: Get analytic information of your data usage and list of beneficiaries enjoying from the data.
      parameters:
      - name: customerId
        in: path
        description: Customer Msisdn. E.123 e.g 2349062058464
        required: true
        schema:
          type: string
      - name: type
        required: true
        in: query
        description: Select the type of query to get
        schema:
          type: string
          enum:
          - provider
          - beneficiary
      - name: startDate
        in: query
        description: Filter the response data by start date
        required: true
        x-example: 20201001
        schema:
          type: string
      - name: endDate
        in: query
        description: Filter the response data by end date
        required: true
        x-example: 20201004
        schema:
          type: string
      - name: pageNum
        in: query
        description: Filter the response data by page number
        required: false
        x-example: 1
        schema:
          type: string
      - name: pageSize
        in: query
        description: Filter the response data by page size
        required: false
        x-example: 5
        schema:
          type: string
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                type: object
                properties:
                  statusCode:
                    type: string
                    description: This is the MADAPI Canonical response Code (it is 4 characters long and it is not the HTTP Status Code which is 3 characters long). Back-end system response are mapped to specific canonical response codes which are returned. More information on these mappings can be found on the MADAPI Confluence Page 'Response Codes'
                  statusMessage:
                    type: string
                    description: Status Message
                  transactionId:
                    type: string
                    description: API generated Id to include for tracing requests
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/DataUsagerInformation'
                  _links:
                    type: object
                    properties:
                      self:
                        type: string
                        example: https://api.mtn.com/v1/customers/23464618463/analytics
        '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'
        '405':
          description: Method No Allowed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error_3'
        '406':
          description: Not acceptable
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error_3'
        '415':
          description: Unsupported media Type
          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: []
    servers:
    - url: https://api.mtn.com/v1/datashare
  /customers/{customerId}/summary:
    get:
      tags:
      - Customer
      summary: Get GDS summary your data usage
      description: Get group data share summary for your dta usage.
      parameters:
      - name: customerId
        in: path
        description: Customer Msisdn. E.123 e.g 2349062058464
        required: true
        schema:
          type: string
      - name: type
        required: true
        in: query
        description: Select the type of query to get
        schema:
          type: string
          enum:
          - provider
          - beneficiary
          - consumer
      - name: startDate
        in: query
        description: Filter the response data by start date
        required: true
        x-example: 20201001
        schema:
          type: string
      - name: endDate
        in: query
        description: Filter the response data by end date
        required: true
        x-example: 20201004
        schema:
          type: string
      - name: pageNum
        in: query
        description: Filter the response data by page number
        required: false
        x-example: 1
        schema:
          type: string
      - name: pageSize
        in: query
        description: Filter the response data by page size
        required: false
        x-example: 5
        schema:
          type: string
      - name: summaryPeriod
        in: query
        description: Shall be mandatory for provider and beneficiary type
        required: false
        schema:
          type: string
          enum:
          - Daily
          - Weekly
          - Monthly
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                type: object
                properties:
                  statusCode:
    

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