openapi: 3.0.1
info:
  title: AccountHolderInfo Aggregator
  description: "The Accountholders API returns basic information of the Accountholder\
    \ including MTN Mobile Money account status. i.e. ACTIVE, SUSPENDED, BLOCKED etc.\
    \ It also support validation of a MoMo accountholder, as well as the verification\
    \ of financial resourceinformation."
  license:
    name: MADAPI
    url: https://developers.mtn.com/
  version: "2.0"
servers:
- url: https://api.mtn.com/
  description: Generated server url
paths:
  /accountholders/{id}/verify:
    post:
      tags:
      - accountholder-controller
      summary: Verify a Partner's Financial Resources
      description: Verify an Accountholder's financial resource information.  This
        requires id - msisdn of customer. Apis accepts several other params as well
        like country code
      operationId: verifyAccountholdersInformation
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
      - name: transactionId
        in: header
        required: false
        schema:
          type: string
          default: ""
      - name: x-country-code
        in: header
        required: true
        schema:
          type: string
      - name: x-authorization
        in: header
        required: false
        schema:
          type: string
      - name: targetsystem
        in: header
        required: true
        schema:
          type: string
      - name: x-origin-channelid
        in: header
        required: false
        schema:
          type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/VerifyRequest'
        required: true
      responses:
        "200":
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/APIResponse'
        "400":
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BadRequestErrorResponse'
        "401":
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UnauthorizedErrorResponse'
        "500":
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ServerErrorResponse'
  /accountholders/{id}/contacts:
    get:
      tags:
      - accountholder-controller
      summary: View AccountHolder favorite contacts
      description: View AccountHolder favorite contacts on AccountHolder Id in TargetSystem.  This
        requires id - msisdn of customer. Apis accepts several other params as well
        like country code
      operationId: getFavoritesAccountHolder
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
      - name: transactionId
        in: header
        required: false
        schema:
          type: string
          default: ""
      - name: idType
        in: header
        required: false
        schema:
          type: string
      - name: x-country-code
        in: header
        required: false
        schema:
          type: string
      - name: x-authorization
        in: header
        required: false
        schema:
          type: string
      - name: targetSystem
        in: header
        required: false
        schema:
          type: string
      - name: x-origin-channelId
        in: header
        required: false
        schema:
          type: string
      - name: type
        in: header
        required: false
        schema:
          type: string
      - name: favoriteType
        in: header
        required: false
        schema:
          type: string
      - name: favoriteSubtype
        in: header
        required: false
        schema:
          type: string
      responses:
        "200":
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/APIResponse'
        "400":
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BadRequestErrorResponse'
        "401":
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UnauthorizedErrorResponse'
        "500":
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ServerErrorResponse'
    post:
      tags:
      - accountholder-controller
      summary: Add AccountHolder favorite contacts
      description: Add AccountHolder favorite contacts on AccountHolder Id in TargetSystem.  This
        requires id - msisdn of customer. Apis accepts several other params as well
        like country code
      operationId: addFavoritesAccountHolder
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
      - name: transactionId
        in: header
        required: false
        schema:
          type: string
          default: ""
      - name: idType
        in: header
        required: false
        schema:
          type: string
      - name: x-country-code
        in: header
        required: false
        schema:
          type: string
      - name: x-authorization
        in: header
        required: false
        schema:
          type: string
      - name: targetSystem
        in: header
        required: false
        schema:
          type: string
      - name: x-origin-channelId
        in: header
        required: false
        schema:
          type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/FavoritesRequest'
        required: true
      responses:
        "200":
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/APIResponse'
        "400":
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BadRequestErrorResponse'
        "401":
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UnauthorizedErrorResponse'
        "500":
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ServerErrorResponse'
    delete:
      tags:
      - accountholder-controller
      summary: Delete AccountHolder favorite contacts
      description: Delete AccountHolder favorite contacts on AccountHolder Id in TargetSystem.  This
        requires id - msisdn of customer. Apis accepts several other params as well
        like country code
      operationId: deleteFavoritesAccountHolder
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
      - name: transactionId
        in: header
        required: false
        schema:
          type: string
          default: ""
      - name: idType
        in: header
        required: false
        schema:
          type: string
      - name: x-country-code
        in: header
        required: false
        schema:
          type: string
      - name: x-authorization
        in: header
        required: false
        schema:
          type: string
      - name: targetSystem
        in: header
        required: false
        schema:
          type: string
      - name: x-origin-channelId
        in: header
        required: false
        schema:
          type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/FavoritesRequest'
        required: true
      responses:
        "200":
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/APIResponse'
        "400":
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BadRequestErrorResponse'
        "401":
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UnauthorizedErrorResponse'
        "500":
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ServerErrorResponse'
  /accountholders/{id}/state:
    patch:
      tags:
      - accountholder-controller
      summary: Block and Unblock AccountHolder
      description: By Interpreting Block and Unblock State on AccountHolder Id in
        TargetSystem.  This requires id - msisdn of customer. Apis accepts several
        other params as well like country code
      operationId: blockUnblockAccountHolders
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
      - name: transactionId
        in: header
        required: false
        schema:
          type: string
          default: ""
      - name: idType
        in: header
        required: false
        schema:
          type: string
      - name: x-country-code
        in: header
        required: false
        schema:
          type: string
      - name: x-authorization
        in: header
        required: false
        schema:
          type: string
      - name: targetSystem
        in: header
        required: false
        schema:
          type: string
      - name: x-origin-channelId
        in: header
        required: false
        schema:
          type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/BlockUnblockRequest'
        required: true
      responses:
        "200":
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/APIResponse'
        "400":
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BadRequestErrorResponse'
        "401":
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UnauthorizedErrorResponse'
        "500":
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ServerErrorResponse'
  /accountholders/{id}:
    get:
      tags:
      - accountholder-controller
      summary: View Accountholder's information
      description: Retrieves the Acountholder's basic information of an MTN customer.
        This requires id - msisdn of customer. Apis accepts several other params as
        well like country code
      operationId: getAccountholdersInformation
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
      - name: transactionId
        in: header
        required: false
        schema:
          type: string
          default: ""
      - name: includeoffnet
        in: query
        required: false
        schema:
          type: boolean
          default: false
      - name: targetSystem
        in: query
        required: false
        schema:
          type: string
          default: ""
      - name: productProviderId
        in: query
        required: false
        schema:
          type: string
      - name: customerIdentifier
        in: query
        required: false
        schema:
          type: string
      - name: x-country-code
        in: header
        required: false
        schema:
          type: string
      - name: x-authorization
        in: header
        required: false
        schema:
          type: string
      - name: x-channel-id
        in: header
        required: false
        schema:
          type: string
      - name: validationType
        in: query
        required: false
        schema:
          type: string
      - name: segment
        in: query
        required: false
        schema:
          type: string
      - name: idType
        in: query
        required: false
        schema:
          type: string
      - name: x-origin-channelid
        in: header
        required: false
        schema:
          type: string
      responses:
        "200":
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/APIResponse'
        "400":
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BadRequestErrorResponse'
        "401":
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UnauthorizedErrorResponse'
        "500":
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ServerErrorResponse'
  /accountholders/{id}/validate:
    get:
      tags:
      - accountholder-controller
      summary: Validate an Individual's Account Status
      description: "Validates the account status of a MoMo customer. By supplying\
        \ the customer's id to validate, MADAPI will send the request to the backend\
        \ system and map the response back to a boolean which will indicate whether\
        \ the customer is a valid MoMo customer on ECW."
      operationId: validateAccountholdersInformation
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
      - name: transactionId
        in: header
        required: false
        schema:
          type: string
          default: ""
      - name: x-country-code
        in: header
        required: true
        schema:
          type: string
      - name: targetSystem
        in: header
        required: false
        schema:
          type: string
      - name: x-authorization
        in: header
        required: false
        schema:
          type: string
      - name: x-channel-id
        in: header
        required: false
        schema:
          type: string
      - name: x-origin-channelid
        in: header
        required: false
        schema:
          type: string
      - name: identityType
        in: query
        required: false
        schema:
          type: string
      responses:
        "200":
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/APIResponse'
        "400":
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BadRequestErrorResponse'
        "401":
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UnauthorizedErrorResponse'
        "500":
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ServerErrorResponse'
  /accountholders/{customerId}/identifications/{idNumber}:
    get:
      tags:
      - accountholder-controller
      summary: Get Extended User Information By Identification
      description: Retrieves the user's information by specifying an ID Type.  This
        requires id - customerId of customer. Apis accepts several other params as
        well like country code
      operationId: getExtendedUserInformationByIdentification
      parameters:
      - name: customerId
        in: path
        required: true
        schema:
          type: string
      - name: idNumber
        in: path
        required: true
        schema:
          type: string
      - name: identificationType
        in: query
        required: true
        schema:
          type: string
          enum:
          - PASSPORT
          - CPFA
          - SRSA
          - NATIONAL_ID
          - OTHER
          - DRIVERS_LICENSE
          - SSNIT
          - SOCIAL_SECURITY
          - NHIS
          - NATIONAL_HEALTH_INSURANCE
          - VOTERS_ID
          - EMPLOYEE_ID
      - name: transactionId
        in: header
        required: false
        schema:
          type: string
      - name: x-country-code
        in: header
        required: true
        schema:
          type: string
      - name: x-authorization
        in: header
        required: false
        schema:
          type: string
      - name: x-origin-channelid
        in: header
        required: false
        schema:
          type: string
      responses:
        "200":
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/APIResponse'
        "400":
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BadRequestErrorResponse'
        "401":
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UnauthorizedErrorResponse'
        "500":
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ServerErrorResponse'
  /accountholderidentification/{id}:
    get:
      tags:
      - accountholder-controller
      summary: View Accountholder's Identification
      description: Retrieves the Acountholder's Identification of an MTN customer.  This
        requires id - msisdn of customer. Apis accepts several other params as well
        like country code
      operationId: getAccountholderIdentification
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
      - name: transactionId
        in: header
        required: false
        schema:
          type: string
          default: ""
      - name: includeoffnet
        in: query
        required: false
        schema:
          type: boolean
          default: false
      - name: x-country-code
        in: header
        required: true
        schema:
          type: string
      - name: x-authorization
        in: header
        required: false
        schema:
          type: string
      - name: x-origin-channelid
        in: header
        required: false
        schema:
          type: string
      responses:
        "200":
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/APIResponse'
        "400":
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BadRequestErrorResponse'
        "401":
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UnauthorizedErrorResponse'
        "500":
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ServerErrorResponse'
components:
  schemas:
    APIResponse:
      type: object
      properties:
        statusCode:
          type: string
        sequenceNo:
          type: string
        _links:
          $ref: '#/components/schemas/Links'
    Links:
      type: object
      additionalProperties:
        $ref: '#/components/schemas/Link'
    VerifyRequest:
      type: object
      properties:
        identificationNumber:
          type: string
        resource:
          type: string
        accountholderids:
          type: array
          items:
            type: string
        extension:
          type: object
    FavoritesRequest:
      type: object
      properties:
        fri:
          type: string
        friType:
          type: string
        favoriteType:
          type: string
        favoriteSubtype:
          type: string
        name:
          type: string
    BlockUnblockRequest:
      type: object
      properties:
        reason:
          type: string
        state:
          type: string
        idType:
          type: string
    BadRequestErrorResponse:
      type: object
      properties:
        statusCode:
          type: string
          example: "5000"
        statusMessage:
          type: string
          example: INVALID_INPUT_PARAMETERS
        supportMessage:
          type: string
          example: The input parameters provided are invalid.
        httpStatus;:
          type: object
          example:
            code: 400
            series: CLIENT_ERROR
            reason: Bad Request
        timestamp:
          type: string
          example: 2025-08-05T20:57:21Z
    UnauthorizedErrorResponse:
      type: object
      properties:
        statusCode:
          type: string
          example: "4000"
        statusMessage:
          type: string
          example: Unauthorized
        supportMessage:
          type: string
          example: The supplied authentication is invalid.
        httpStatus;:
          type: object
          example:
            code: 401
            series: CLIENT_ERROR
            reason: Unauthorized
        timestamp:
          type: string
          example: 2025-08-05T20:57:21Z
    ServerErrorResponse:
      type: object
      properties:
        statusCode:
          type: string
          example: "3001"
        statusMessage:
          type: string
          example: INTERNAL_SERVER_ERROR
        supportMessage:
          type: string
          example: An internal server error occurred and processing could not be completed.
        httpStatus;:
          type: array
          example:
            code: 500
            series: SERVER_ERROR
            reason: Internal Server Error
        timestamp:
          type: string
          example: 2025-08-05T20:57:21Z
    Link:
      type: object
      properties:
        href:
          type: string
        hreflang:
          type: string
        title:
          type: string
        type:
          type: string
        deprecation:
          type: string
        profile:
          type: string
        name:
          type: string
        templated:
          type: boolean