MTN Group Usage Historical Information API

openapi: 3.2.0
info:
  version: 1.0.0
  title: Customer Identification Usage Historical Information API
  description: "The Customer Identification API provides information about a customer and their historical usage events on voice, data, SMS, Roaming etc. Information can be retrieved by stating the date range for the period the API consumer is interested in. It will return date and time on which a specific event occurred on a customer's MSISDN as queried by the API consumer\n### Supported Operations\n\n  1. **Recharge and Usage Historical Information**\n      - **subscriberUsage:** Data, Voice, SMS call events\n            records\n      - **roamingUsage**: Data, Voice, SMS call events\n            records for Roaming\n      - **rechargeHistory:** Airtime Recharge Events\n      - **daUsageHistory:** Dedicated Account Balance usage\n      - **mainAccountUsage:** Events that used the Main Airtime\n      - **accountAdjustments:** Bucket Balance adjustment events that\n      happened on MA and DA's\n      - **internetUsageDetails:** Detailed Data usage events\n      - **validateKYC**: Validates whether msisdn and NIN values provided match or don't match\n \n  2. **Xtratime**\n      - View Loan Details: gets the list of open loans and their data for a subscriber of Xtratime product\n      - View Transaction Detail:  used to get a list of the history for loans (Advance/Recoveries) for a subscriber of xtratime product.\n      - Customer Eligibility: used to retrieve the list of denomination identifiers i.e. loan bands for which the subscriber is eligible at the time of the request.\n      - Customer Profile: used to retrieve the credit limit and balances list of the customer\n      \n  3. **Customer Information**\n      - Query Customer Data: Returns kyc and summary statistics on usage data for a subscriber msisdn. **Note, depending on the priviledges assigned to a 3PP all/less data is returned.**\n      - Query Merchant Data: Returns kyc and summary statistics on usage data for a momopay merchant msisdn. **Note, depending on the priviledges assigned to a 3PP all/less data is returned.**"
  contact:
    email: developer-support@mtn.com
    name: MTN API Support
servers:
- url: https://api.mtn.com/v1/customerIdentification/
security: []
tags:
- name: Usage Historical Information
paths:
  /customer:
    get:
      description: Get Usage, Roaming, Recharge History, Customer Profile or Eligibility status of a customer, identified by an MSISDN
      summary: Get Usage, Roaming, Recharge History, Customer Profile or Eligibility status of a customer, identified by an MSISDN
      tags:
      - Usage Historical Information
      operationId: GetUsage,Roaming,RechargeHistory,CustomerProfileorEligibilitystatusofacustomer,identifiedbyanMSISDN
      deprecated: false
      parameters:
      - name: customerId
        in: query
        required: true
        description: MSISDN of the customer
        schema:
          type: number
          format: double
      - name: partnerId
        in: query
        required: true
        description: Unique identifier of the system from which the request for customer information is coming. This is to be assigned by the back-end provider system
        schema:
          type: number
          format: double
      - name: operationName
        in: query
        required: true
        description: 'Name assigned to the task to be performed. Below are the possible values;

          - **subscriberUsage:** Data, Voice, SMS call events records

          - **roamingUsage:** Data, Voice, SMS call events records for Roaming

          - **rechargeHistory:** Airtime Recharge History

          - **daUsageHistory:** Dedicated Account Balance usage

          - **mainAccountUsage:** Events that used the Main Airtime

          - **accountAdjustments:** Bucket Balance adjustment events that

          happened on MA and DA''s

          - **internetUsageDetails:** Detailed Data usage events

          - **viewloandetailsCVAS:** gets the list of open loans and their data for a subscriber of Xtratime product

          - **viewtrxdetailsCVAS:** used to get a list of the history for loans (Advance/Recoveries) for a subscriber of xtratime product.

          - **checkEligibilityCVAS:** used to retrieve the list of denomination identifiers i.e. loan bands for which the subscriber is eligible at the time of the request.

          - **checkProfileCVAS:** used to retrieve the credit limit and balances list of the customer

          - **validateKYC:** confirm NIN and MSISDN are a match/no-match'
        schema:
          type: string
          enum:
          - subscriberUsage
          - roamingUsage
          - rechargeHistory
          - daUsageHistory
          - mainAccountUsage
          - accountAdjustments
          - internetUsageDetails
          - viewloandetailsCVAS
          - viewtrxdetailsCVAS
          - checkEligibilityCVAS
          - checkProfileCVAS
          - validateKYC
      - name: IdNumber
        in: query
        required: false
        description: NIN of the msisdn for which a match or no match is required . It is only applicable and mandatory if the operationName is set to validateKYC.
        schema:
          type: string
      - name: startDate
        in: query
        required: false
        description: 'Start Date from which information is required. Format; YYYYMMDD


          *Only applicable and mandatory when **operationName** = subscriberUsage, roamingUsage, rechargeHistory, daUsageHistory, mainAccountUsage, accountAdjustments, internetUsageDetails*'
        schema:
          type: number
          format: double
      - name: endDate
        in: query
        required: false
        description: 'End Date to which information is required. Format; YYYYMMDD


          *Only applicable when **operationName** = subscriberUsage, roamingUsage, rechargeHistory, daUsageHistory, mainAccountUsage, accountAdjustments, internetUsageDetails*'
        schema:
          type: number
          format: double
      - name: status
        in: query
        required: false
        description: 'Status of the loan


          *Only applicable when **operationName** = viewloandetailsCVAS*'
        schema:
          type: string
          enum:
          - open
          - closed
      - name: offset
        in: query
        required: false
        description: 'Indicates the max number of loan transaction to return. This is a limiter and can not exceed the project maximum.


          *Only applicable when **operationName** = viewtrxdetailsCVAS*'
        schema:
          type: number
          format: double
      - name: cvasBandName
        in: query
        required: false
        description: 'Specifies a specific loan band against which eligibility is checked.


          *Only applicable when **operationName** = checkEligibilityCVAS*'
        schema:
          type: string
      - name: cvasBandGroup
        in: query
        required: false
        description: 'Specifies the loan bands of the group against which eligibility is checked.


          *Only applicable when **operationName** = checkEligibilityCVAS*'
        schema:
          type: number
          format: double
      - name: responseType
        in: query
        required: false
        description: 'Specifies the level of information to return.


          *Only applicable when **operationName** = checkEligibilityCVAS*

          - B stands for "Basic". Returns Eligibility status only

          - E stands for "Extend". Returns Eligibility status and the list of eligible bands.'
        schema:
          type: string
          enum:
          - B
          - E
          default: E
      - name: eligibilityCheck
        in: query
        required: false
        description: 'Specifies the eligibility rules to run.


          *Only applicable when **operationName** = checkEligibilityCVAS*

          - B stands for "Basic". Without IN interaction

          - E stands for "Extend". With complete eligibility rules'
        schema:
          type: string
          enum:
          - B
          - E
          default: E
      - name: usageType
        in: query
        required: false
        description: 'Specifies the type of usage to be fetched.


          *Only applicable when **operationName** = subscriberUsage*.'
        schema:
          type: string
          enum:
          - ALL
          - VOICE
          - SMS
          - DATA
          default: ALL
      responses:
        '200':
          description: OK
          headers: {}
          content:
            application/json:
              schema:
                default: ''
              example:
                APIStatus:
                  msisdn: '242068021197'
                  requestId: '4940324720466238117'
                  dateRange:
                  - '20210614'
                  - '20210614'
                  maxRecs: 5
                  numRecs: 5
                  pageNum: 1
                  submittedTime: 2021-08-19 15:19:49.142000
                  duration: 83
                  statusCode: 200
                  statusMsg: OK
                  APIData:
                  - duration: 1
                    charge_duration: 1
                    timestamp: 20200922212007+0300
                    description: SMS
                    call_type: ONNET
                    date_key: 20200922
                    called_msisdn: '256800205353'
                    amount: '0.000000'
                    service_class: '31'
                    offer_desc: ''
                    timestamp_v: 1600809607000
                    unit: M
                    call_direction: OUTGOING
                    call_reference_no: ''
                    da_id: '20'
                    discount_amt: ''
                    da_balance_before_amt: '200'
                    package_cd: P1000
                    base_station_id: 629 10 121 11014
                    ma_balance_before_amt: '0.013333'
                    da_balance_after_amt: '0'
                    da_id_description: BUNDLE
                    bytes_sent_qty: ''
                    da_value_amt: '200'
                    call_reference_number: '3976963048'
                    discount_cd: ''
                    currency_cd: XAF
                    event_subtype_cd: '0'
                    source_system_cd: CCN
                    apn_cd: ''
                    event_cd: VOICE
                    discount_pct: '0'
                    event_subtype_desc_txt: null
                    served_msisdn_nr: '242068021197'
                    subscriber_type: PREPAID
                    called_numbner: '65938200'
                    bytes_received_qty: ''
                    ma_balance_after_amt: '0.013333'
                  - recharge_value_after: 900
                    timestamp: 20210610090705
                    date_key: 20210610
                    recharge_type: RCG_MMT_AIR_MOBILE_MONEY
                    recharge_value_before: 0
                    transaction_id: '1282815489'
                    recharge_amount: 900
                    timestamp_v: 1599233410000
                    recharge_channel: EXTEVDS|EVDSMOMO
                    re_method: ''
                    base_station_id: ''
                    re_tax: ''
                    re_denomination: '900.0'
                    re_bundle: DIY_BONUS
                    re_msisdn_nsk: '242066223438'
                    service_id: '3'
                    re_account: DA_ID_253
                    re_validity: '5'
                  - duration: 16
                    description: VOICE
                    call_type: VOICE
                    date_key: 20200916
                    called_msisdn: '256758130545'
                    call_date: '2020-09-16 13:47:28'
                    main_bal_after: 7936
                    service_class: MTN Call Per Second
                    call_cost: 64
                    main_bal_before: 8000
                    timestamp_v: 1600228800000
                    charge_unit: M
                  - origtransactionid: '12345'
                    balance_before: '0.014687'
                    node_id: USSDug
                    date_key: 20210818
                    call_date: 20210818191922
                    balance_after: '500.014687'
                    change: '-500.0'
                    timestamp_v: 1600255847000
                    node: madapiST
                    m2u_receiver: ''
                    service_id: '242065933826'
                    event_subtype_cd: Credit
                    adj_account: MASTER
                    adj_validity: ''
                    adj_acct_source: ERS1A
                    adj_tran_type: ERS1A
                    m2u_sender: ''
                  - imei: '911563554605990'
                    hour_enrich: 9
                    date_key: 20200916
                    application_v: DNS
                    egn_sub_protocol_v: dns
                    data_usage_type: 2
                    egn_sub_protocol_id_n: 79
                    downlink_traffic: 6148
                    uplink_traffic: 3018
                    total_traffic: 9166
                    timestamp_v: 1600228800000
                    apn: internet
                    imsi: 641101909028494
                  - call_direction: I
                    package_cd: P1000
                    package_description: MTN FREE~1.0
                    event_unit_cd: XAF
                    call_duration_qty: '24'
                    country: Congo
                    served_imsi_nr: null
                    bytes_sent_qty: 0
                    date_key: 20210812
                    sdr_charge_amt: '0'
                    other_nr: '242055286670'
                    cdr_ts: '2021-08-12 07:33:39.0'
                    event_value_amt: '1240000'
                    msisdn_nsk: '242066173079'
                    event_desc_txt: VOICE
                    currency_cd: XAF
                    source_system_cd: PM RATED
                    event_subtype_cd: ''
                    event_cd: '0'
                    event_subtype_desc_txt: ''
                    conversion_rate: '0'
                    event_dt: '20210812'
                    bytes_received_qty: '0'
        '400':
          description: Bad Request
          headers: {}
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/customerUsage'
              example:
                response:
                  errorCode: '1103'
                  errorDescription: Invalid parameter value. The name of the parameter will be provided
                  msisdn: '22977777'
                  when: 1519980424641
                  status: ERROR
                loanList: []
                operationList: null
                APIData:
                  status: NO_MATCH
                  create_dt: 20220324
                  submission_time: 20220324 08:41:01
                  request_id: e8f39b6a46364875a4a89730e3925bc4
                  response_time_sec: '0.0417'
        '401':
          description: Unauthorized
          headers: {}
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/customerUsage'
        '403':
          description: Forbidden
          headers: {}
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/customerUsage'
        '404':
          description: Not Found
          headers: {}
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/customerUsage'
        '500':
          description: Internal Server Error
          headers: {}
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/customerUsage'
      security:
      - ApiKeyAuth: []
components:
  schemas:
    APIStatus:
      title: APIStatus
      type: object
      properties:
        msisdn:
          description: MSISDN of the customer whose information has been returned
          example: '256789999781'
          type: string
        requestId:
          description: internally generated transaction Id from the backend
          example: '4993609756309740126'
          type: string
        dateRange:
          description: Date range of the returned information
          type: array
          items:
            $ref: '#/components/schemas/DateRange'
        maxRecs:
          description: Maximum number of records available for the given date range
          type: integer
          format: int32
        numRecs:
          description: Number of records returned. 0 for no records returned.
          type: number
          format: double
        pageNum:
          type: object
          allOf:
          - $ref: '#/components/schemas/PageNum'
          - description: Maximum number of records that can be returned in a single response
        submittedTime:
          description: Date time stamp when the request for information was made
          example: 2020-09-01 17:08:38.549000
          type: string
        duration:
          description: Duration taken to process the request in milliseconds
          type: number
          format: double
        statusCode:
          description: Response status code
          example: 200
          type: number
          format: double
        statusMsg:
          description: Description for the response status code
          example: OK
          type: string
    DateRange:
      title: DateRange
      type: object
      properties:
        startdate:
          description: Format; YYYYMMDD
          type: string
        enddate:
          description: Format; YYYYMMDD
          type: string
    PageNum:
      title: PageNum
      description: Maximum number of records that can be returned in a single response
      type: integer
      format: int32
      enum:
      - 50
    customerUsage:
      title: customerUsage
      type: object
      properties:
        APIStatus:
          $ref: '#/components/schemas/APIStatus'
        APIData:
          description: Detailed information returned about the subscriber
          type: array
          items: {}
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      name: X-API-Key
      in: header