openapi: 3.0.1
info:
  title: PUK SingleView
  description: "The Get PUK SingleView Aggregator service provides a unified interface\
    \ for retrieving PUK (Personal Unblocking Key) information from various backend\
    \ systems. This service streamlines the process of accessing PUK data, ensuring\
    \ accuracy and efficiency for customer support and self-service portals. It aggregates\
    \ data from multiple sources to present a comprehensive view of PUK details, enhancing\
    \ the overall customer experience."
  license:
    name: MADAPI
    url: https://developers.mtn.com/
  version: 3.0.0 - Last updated date:2026-08-18 22:20:38
servers:
- url: https://api.mtn.com/v1
  description: Production Server
security:
- OAuth2: []
tags:
- name: GetPukAggregator
paths:
  /customers/{customerId}/sim/simDetails:
    get:
      tags:
      - GetPukAggregator
      summary: Retrieves the PUK (Personal Unblocking Key) details for a specified
        customer.
      description: "This endpoint is designed to securely fetch and provide the PUK\
        \ details associated with a given customer ID. It integrates with backend\
        \ systems to ensure the accurate retrieval of unblocking keys, which are essential\
        \ for restoring access to locked SIM cards."
      operationId: GetPukAggregator_get_aggregateGetPuk_customerscustomerIds
      parameters:
      - name: customerId
        in: path
        required: true
        schema:
          type: string
      - name: targetSystem
        in: header
        required: false
        schema:
          type: string
      - name: transactionId
        in: header
        required: false
        schema:
          type: string
      - name: x-authorization
        in: header
        required: false
        schema:
          type: string
      - name: x-country-code
        in: header
        required: false
        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 TMF908-iot-Device
            Management flows.
          content:
            application/json:
              schema:
                title: ApiResponse
                type: object
                properties:
                  data:
                    title: Data
                    type: object
                    properties:
                      simInformation:
                        type: array
                        items:
                          title: SimInformation
                          type: object
                          properties:
                            code:
                              type: string
                            name:
                              type: string
                            value:
                              type: string
                      id:
                        type: string
                      fullName:
                        type: string
                      idNumber:
                        type: string
                      alternativePhoneNumber:
                        type: string
                      registrationDate:
                        type: string
                      registrationStatus:
                        type: string
                      businessType:
                        type: string
                      customerType:
                        type: string
                      requestType:
                        type: string
                      productDetails:
                        type: array
                        items:
                          type: string
                      mobileInformation:
                        type: string
                      maxNData:
                        type: array
                        items:
                          title: MaxNData
                          type: object
                          properties:
                            role:
                              type: string
                  error:
                    title: APIError
                    type: object
                    properties:
                      statusMessage:
                        type: string
                      supportMessage:
                        type: string
                      transactionId:
                        type: string
                      timestamp:
                        type: string
                      path:
                        type: string
                      method:
                        type: string
                      statusCode:
                        type: string
                      downstreamStatusCode:
                        type: integer
                        format: int32
                      sequenceNo:
                        type: string
                  statusCode:
                    type: string
                  statusMessage:
                    type: string
                  transactionId:
                    type: string
                  supportMessage:
                    type: string
                  timestamp:
                    type: string
                  _links:
                    $ref: '#/components/schemas/za_co_mtn_getpuk_apiresponse_Links'
        "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
  /payments/payment-agreement/eligibility:
    get:
      tags:
      - GetPukAggregator
      summary: Checks the eligibility status for a payment agreement for a given billing
        account number.
      description: "This endpoint assesses whether a customer is eligible to enter\
        \ into a payment agreement. It evaluates various financial and historical\
        \ criteria associated with the provided billing account number to determine\
        \ eligibility, facilitating flexible payment solutions."
      operationId: GetPukAggregator_get_aggregateGetEligibilty_paymentspaymentagree
      parameters:
      - name: billingAccountNumber
        in: query
        required: true
        schema:
          type: string
      - name: transactionId
        in: header
        required: false
        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 TMF908-iot-Device
            Management flows.
          content:
            application/json:
              schema:
                title: PaymentPromiseResponseEligibilty
                type: object
                properties:
                  statusCode:
                    type: string
                  statusMessage:
                    type: string
                  supportMessage:
                    type: string
                  transactionId:
                    type: string
                  data:
                    title: Data
                    type: object
                    properties:
                      PromiseToPayEligibilityDetails:
                        title: PromiseToPayEligibilityDetails
                        type: object
                        properties:
                          eligibilityStatus:
                            type: string
                          accountBalance:
                            type: string
                          minimumAmount:
                            type: string
                          paymentStartDate:
                            type: string
                  _links:
                    title: Links
                    type: object
                    properties:
                      self:
                        title: Self
                        type: object
                        properties:
                          href:
                            type: string
                  timeStamp:
                    type: string
                  timestamp:
                    type: string
                  path:
                    type: string
                  method:
                    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
components:
  schemas:
    za_co_mtn_getpuk_apiresponse_Self:
      title: Self
      type: object
      properties:
        href:
          type: string
    za_co_mtn_getpuk_apiresponse_SimInformation:
      title: SimInformation
      type: object
      properties:
        code:
          type: string
        name:
          type: string
        value:
          type: string
    za_co_mtn_getpuk_configuration_response_Data:
      title: Data
      type: object
      properties:
        PromiseToPayEligibilityDetails:
          title: PromiseToPayEligibilityDetails
          type: object
          properties:
            eligibilityStatus:
              type: string
            accountBalance:
              type: string
            minimumAmount:
              type: string
            paymentStartDate:
              type: string
    za_co_mtn_getpuk_apiresponse_Links:
      title: Links
      type: object
      properties:
        self:
          title: Self
          type: object
          properties:
            href:
              type: string
    za_co_mtn_getpuk_apiresponse_ApiResponse:
      title: ApiResponse
      type: object
      properties:
        data:
          title: Data
          type: object
          properties:
            simInformation:
              type: array
              items:
                title: SimInformation
                type: object
                properties:
                  code:
                    type: string
                  name:
                    type: string
                  value:
                    type: string
            id:
              type: string
            fullName:
              type: string
            idNumber:
              type: string
            alternativePhoneNumber:
              type: string
            registrationDate:
              type: string
            registrationStatus:
              type: string
            businessType:
              type: string
            customerType:
              type: string
            requestType:
              type: string
            productDetails:
              type: array
              items:
                type: string
            mobileInformation:
              type: string
            maxNData:
              type: array
              items:
                title: MaxNData
                type: object
                properties:
                  role:
                    type: string
        error:
          title: APIError
          type: object
          properties:
            statusMessage:
              type: string
            supportMessage:
              type: string
            transactionId:
              type: string
            timestamp:
              type: string
            path:
              type: string
            method:
              type: string
            statusCode:
              type: string
            downstreamStatusCode:
              type: integer
              format: int32
            sequenceNo:
              type: string
        statusCode:
          type: string
        statusMessage:
          type: string
        transactionId:
          type: string
        supportMessage:
          type: string
        timestamp:
          type: string
        _links:
          $ref: '#/components/schemas/za_co_mtn_getpuk_apiresponse_Links'
    za_co_mtn_getpuk_apiresponse_PromiseToPayEligibilityDetails:
      title: PromiseToPayEligibilityDetails
      type: object
      properties:
        eligibilityStatus:
          type: string
        accountBalance:
          type: string
        minimumAmount:
          type: string
        paymentStartDate:
          type: string
    za_co_mtn_getpuk_apiresponse_PaymentPromiseResponseEligibilty:
      title: PaymentPromiseResponseEligibilty
      type: object
      properties:
        statusCode:
          type: string
        statusMessage:
          type: string
        supportMessage:
          type: string
        transactionId:
          type: string
        data:
          title: Data
          type: object
          properties:
            PromiseToPayEligibilityDetails:
              title: PromiseToPayEligibilityDetails
              type: object
              properties:
                eligibilityStatus:
                  type: string
                accountBalance:
                  type: string
                minimumAmount:
                  type: string
                paymentStartDate:
                  type: string
        _links:
          title: Links
          type: object
          properties:
            self:
              title: Self
              type: object
              properties:
                href:
                  type: string
        timeStamp:
          type: string
        timestamp:
          type: string
        path:
          type: string
        method:
          type: string
    za_co_mtn_getpuk_apiresponse_MaxNData:
      title: MaxNData
      type: object
      properties:
        role:
          type: string
    com_mtn_madapi_commons_models_error_APIError:
      title: APIError
      type: object
      properties:
        statusMessage:
          type: string
        supportMessage:
          type: string
        transactionId:
          type: string
        timestamp:
          type: string
        path:
          type: string
        method:
          type: string
        statusCode:
          type: string
        downstreamStatusCode:
          type: integer
          format: int32
        sequenceNo:
          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
    za_co_mtn_getpuk_apiresponse_Data:
      title: Data
      type: object
      properties:
        simInformation:
          type: array
          items:
            title: SimInformation
            type: object
            properties:
              code:
                type: string
              name:
                type: string
              value:
                type: string
        id:
          type: string
        fullName:
          type: string
        idNumber:
          type: string
        alternativePhoneNumber:
          type: string
        registrationDate:
          type: string
        registrationStatus:
          type: string
        businessType:
          type: string
        customerType:
          type: string
        requestType:
          type: string
        productDetails:
          type: array
          items:
            type: string
        mobileInformation:
          type: string
        maxNData:
          type: array
          items:
            title: MaxNData
            type: object
            properties:
              role:
                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