openapi: 3.0.1
info:
  title: 'MTN Customer Identification '
  description: "This API provides comprehensive customer identification capabilities\
    \ for MTN operations including KYC validation, profile management, customer data\
    \ retrieval, and identity verification. The service integrates with various identification\
    \ systems and provides standardized APIs for customer identification across the\
    \ MTN ecosystem."
  license:
    name: MADAPI
    url: https://developers.mtn.com/
  version: 3.0.0 - Last updated date:2026-09-02 10:58:55
servers:
- url: https://api.mtn.com/v1
  description: Production Server
security:
- OAuth2: []
tags:
- name: CustomerIdentification
paths:
  /customer:
    get:
      tags:
      - CustomerIdentification
      summary: Retrieve Customer Data
      description: "Retrieves comprehensive customer data for a specific MSISDN including\
        \ usage history, profile information, and identity verification details. The\
        \ endpoint supports various operation types and provides secure access through\
        \ authorization claims validation."
      operationId: CustomerIdentificationAggregatorService_get_queryCustomerUsageHistory_customer
      parameters:
      - name: accountType
        in: query
        required: false
        schema:
          type: string
      - name: bandGroup
        in: query
        required: false
        schema:
          type: string
      - name: bandName
        in: query
        required: false
        schema:
          type: string
      - name: customerId
        in: query
        required: false
        schema:
          type: string
      - name: customerIdHash
        in: query
        required: false
        schema:
          type: string
      - name: eligibilityCheck
        in: query
        required: false
        schema:
          type: string
      - name: endDate
        in: query
        required: false
        schema:
          type: string
      - name: idNumber
        in: query
        required: false
        schema:
          type: string
      - name: indexOffset
        in: query
        required: false
        schema:
          type: string
      - name: numOfTransactions
        in: query
        required: false
        schema:
          type: string
      - name: offset
        in: query
        required: false
        schema:
          type: string
      - name: operationName
        in: query
        required: true
        schema:
          type: string
      - name: partnerId
        in: query
        required: false
        schema:
          type: string
      - name: providerId
        in: query
        required: false
        schema:
          type: string
      - name: referenceId
        in: query
        required: false
        schema:
          type: string
      - name: responseType
        in: query
        required: false
        schema:
          type: string
      - name: startDate
        in: query
        required: false
        schema:
          type: string
      - name: transactionId
        in: header
        required: false
        schema:
          type: string
      - name: usageType
        in: query
        required: false
        schema:
          type: string
      - name: x-authorization-claims
        in: header
        required: true
        schema:
          type: string
      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 customer
            identification flows.
          content:
            application/json:
              schema:
                title: ResponseEntity
                type: object
                properties:
                  status:
                    title: HttpStatusCode
                    type: object
                  headers:
                    type: object
                    additionalProperties:
                      type: object
                  body:
                    type: string
        "400":
          description: "Bad request. Invalid request parameters, missing required\
            \ fields, or validation errors."
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/APIError'
              example:
                statusCode: "400"
                statusMessage: "Bad request. Invalid request parameters, missing required\
                  \ fields, or validation errors."
                supportMessage: API_ERROR
                transactionId: "1234567890"
                sequenceNo: "20250115120000001"
                timestamp: 2025-01-15T12:00:00Z
        "401":
          description: "Unauthorized. Invalid or missing authorization credentials,\
            \ insufficient permissions, or authentication failure."
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/APIError'
              example:
                statusCode: "401"
                statusMessage: "Unauthorized. Invalid or missing authorization credentials,\
                  \ insufficient permissions, or authentication failure."
                supportMessage: API_ERROR
                transactionId: "1234567890"
                sequenceNo: "20250115120000001"
                timestamp: 2025-01-15T12:00:00Z
        "403":
          description: Forbidden. Access denied. The request is valid but the server
            refuses to perform it.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/APIError'
              example:
                statusCode: "403"
                statusMessage: Forbidden. Access denied. The request is valid but
                  the server refuses to perform it.
                supportMessage: API_ERROR
                transactionId: "1234567890"
                sequenceNo: "20250115120000001"
                timestamp: 2025-01-15T12:00:00Z
        "404":
          description: Not found. The requested resource was not found or does not
            exist.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/APIError'
              example:
                statusCode: "404"
                statusMessage: Not found. The requested resource was not found or
                  does not exist.
                supportMessage: API_ERROR
                transactionId: "1234567890"
                sequenceNo: "20250115120000001"
                timestamp: 2025-01-15T12:00:00Z
        "500":
          description: "Internal server error. Unexpected system failure, database\
            \ connectivity issues, or external service integration problems."
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/APIError'
              example:
                statusCode: "500"
                statusMessage: "Internal server error. Unexpected system failure,\
                  \ database connectivity issues, or external service integration\
                  \ problems."
                supportMessage: API_ERROR
                transactionId: "1234567890"
                sequenceNo: "20250115120000001"
                timestamp: 2025-01-15T12:00:00Z
        "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'
              example:
                statusCode: "502"
                statusMessage: Bad gateway. The server acting as a gateway received
                  an invalid response from an upstream server.
                supportMessage: API_ERROR
                transactionId: "1234567890"
                sequenceNo: "20250115120000001"
                timestamp: 2025-01-15T12:00:00Z
        "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'
              example:
                statusCode: "503"
                statusMessage: Service unavailable. The server is temporarily unable
                  to handle the request due to maintenance or overload.
                supportMessage: API_ERROR
                transactionId: "1234567890"
                sequenceNo: "20250115120000001"
                timestamp: 2025-01-15T12:00:00Z
      deprecated: false
    post:
      tags:
      - CustomerIdentification
      summary: Query Customer Data
      description: Allows querying customer data for an MTN customer. This endpoint
        requires authentication and authorization claims to be present in the request
        headers.
      operationId: CustomerIdentificationAggregatorService_post_queryCustomerData_customer
      parameters:
      - name: headers
        in: header
        required: true
        schema:
          type: string
      requestBody:
        content:
          application/json:
            schema:
              title: CustomerData
              type: object
              properties:
                pageNum:
                  type: integer
                  format: int32
                msisdn:
                  type: string
                attributes:
                  type: string
                options:
                  type: string
                startdate:
                  type: string
                enddate:
                  type: string
                operationName:
                  type: string
                operationValue:
                  type: integer
                  format: int32
                subscriberId:
                  type: string
                loanerId:
                  type: string
                userId:
                  type: string
                appName:
                  type: string
                hostName:
                  type: string
                maxResults:
                  type: integer
                  format: int32
                pageSize:
                  type: integer
                  format: int32
                format:
                  type: string
                customerId:
                  type: string
                partnerId:
                  type: string
                userToken:
                  type: string
                providerId:
                  type: string
                customerToken:
                  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 customer
            identification flows.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/com_mtn_aggregator_models_CustomerData'
        "400":
          description: "Bad request. Invalid request parameters, missing required\
            \ fields, or validation errors."
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/APIError'
              example:
                statusCode: "400"
                statusMessage: "Bad request. Invalid request parameters, missing required\
                  \ fields, or validation errors."
                supportMessage: API_ERROR
                transactionId: "1234567890"
                sequenceNo: "20250115120000001"
                timestamp: 2025-01-15T12:00:00Z
        "401":
          description: "Unauthorized. Invalid or missing authorization credentials,\
            \ insufficient permissions, or authentication failure."
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/APIError'
              example:
                statusCode: "401"
                statusMessage: "Unauthorized. Invalid or missing authorization credentials,\
                  \ insufficient permissions, or authentication failure."
                supportMessage: API_ERROR
                transactionId: "1234567890"
                sequenceNo: "20250115120000001"
                timestamp: 2025-01-15T12:00:00Z
        "403":
          description: Forbidden. Access denied. The request is valid but the server
            refuses to perform it.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/APIError'
              example:
                statusCode: "403"
                statusMessage: Forbidden. Access denied. The request is valid but
                  the server refuses to perform it.
                supportMessage: API_ERROR
                transactionId: "1234567890"
                sequenceNo: "20250115120000001"
                timestamp: 2025-01-15T12:00:00Z
        "404":
          description: Not found. The requested resource was not found or does not
            exist.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/APIError'
              example:
                statusCode: "404"
                statusMessage: Not found. The requested resource was not found or
                  does not exist.
                supportMessage: API_ERROR
                transactionId: "1234567890"
                sequenceNo: "20250115120000001"
                timestamp: 2025-01-15T12:00:00Z
        "500":
          description: "Internal server error. Unexpected system failure, database\
            \ connectivity issues, or external service integration problems."
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/APIError'
              example:
                statusCode: "500"
                statusMessage: "Internal server error. Unexpected system failure,\
                  \ database connectivity issues, or external service integration\
                  \ problems."
                supportMessage: API_ERROR
                transactionId: "1234567890"
                sequenceNo: "20250115120000001"
                timestamp: 2025-01-15T12:00:00Z
        "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'
              example:
                statusCode: "502"
                statusMessage: Bad gateway. The server acting as a gateway received
                  an invalid response from an upstream server.
                supportMessage: API_ERROR
                transactionId: "1234567890"
                sequenceNo: "20250115120000001"
                timestamp: 2025-01-15T12:00:00Z
        "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'
              example:
                statusCode: "503"
                statusMessage: Service unavailable. The server is temporarily unable
                  to handle the request due to maintenance or overload.
                supportMessage: API_ERROR
                transactionId: "1234567890"
                sequenceNo: "20250115120000001"
                timestamp: 2025-01-15T12:00:00Z
      deprecated: false
components:
  schemas:
    org_springframework_http_HttpStatusCode:
      title: HttpStatusCode
      type: object
    com_mtn_aggregator_models_CustomerData:
      title: CustomerData
      type: object
      properties:
        pageNum:
          type: integer
          format: int32
        msisdn:
          type: string
        attributes:
          type: string
        options:
          type: string
        startdate:
          type: string
        enddate:
          type: string
        operationName:
          type: string
        operationValue:
          type: integer
          format: int32
        subscriberId:
          type: string
        loanerId:
          type: string
        userId:
          type: string
        appName:
          type: string
        hostName:
          type: string
        maxResults:
          type: integer
          format: int32
        pageSize:
          type: integer
          format: int32
        format:
          type: string
        customerId:
          type: string
        partnerId:
          type: string
        userToken:
          type: string
        providerId:
          type: string
        customerToken:
          type: string
    APIError:
      title: APIError
      required:
      - statusCode
      - statusMessage
      type: object
      properties:
        statusCode:
          type: string
          description: Error status code
        statusMessage:
          type: string
          description: Human-readable error message
        supportMessage:
          type: string
          description: Technical support message or error code for troubleshooting
        transactionId:
          type: string
          description: Transaction identifier for tracking and correlation
        sequenceNo:
          type: string
          description: Sequence number for request tracking
        timestamp:
          type: string
          description: Error timestamp in ISO 8601 format
          format: date-time
        path:
          type: string
          description: API endpoint path where the error occurred
        method:
          type: string
          description: HTTP method of the request that caused the error
        downstreamStatusCode:
          type: string
          description: Downstream service error code if applicable
      description: Generic MADAPI error response structure
    org_springframework_http_ResponseEntity:
      title: ResponseEntity
      type: object
      properties:
        status:
          title: HttpStatusCode
          type: object
        headers:
          type: object
          additionalProperties:
            type: object
        body:
          type: string
  securitySchemes:
    OAuth2:
      type: oauth2
      flows:
        clientCredentials:
          tokenUrl: https://api.mtn.com/v1/oauth/access_token
          scopes: {}
    Bearer:
      type: http
      description: Bearer token received from OAuth2.0 authentication with the MADAPI
      scheme: bearer
      bearerFormat: JWT