MTN Group Subscriberinfo API

openapi: 3.2.0
info:
  description: This API to be used to manage a Subscriber information.
  version: 1.0.2
  title: Subscriber Management Subscriberinfo API
servers:
- url: https://api.mtn.com/v1
security:
- ApiKeyAuth: []
- OAuth2: []
tags:
- name: subscriberinfo
paths:
  /subscriber/{id}:
    get:
      operationId: retrieveSubscriberinfoById
      summary: Retrieves a Subscriber info by ID
      description: This operation retrieves a subscriber's detail based upon the filter criteria.
      tags:
      - subscriberinfo
      parameters:
      - name: id
        description: Identifier of the subscriber
        required: true
        in: path
        schema:
          type: string
      - name: queryType
        description: '''personalDetail'' will return only personal data of the subscriber, i.e., Subscriberinfo object. ''identityDetail'' will return only identity information of the subscriber , i.e., SubscriberIdentification object. ''addressDetail'' will return only address of the subscriber , i.e., Address object. ''deviceDetail'' will return only device related information of the subscriber like puk number , imsi number etc. It will return only SubscriberAsset object in response. ''basicProfile'' will return subscriber details , like- subscriber id , subscriber type, subscriber status etc. along with subscriber asset information. ''completeProfile'' will return complete information of the subscriber. It will return SubscriberProfile object in response.'
        required: true
        in: query
        schema:
          type: string
          enum:
          - personalDetail
          - identityDetail
          - addressDetail
          - deviceDetail
          - basicProfile
          - completeProfile
          default: basicProfile
      - name: transactionId
        in: header
        required: false
        description: Unique transaction id genereted by client system. This will be used to track requests
        schema:
          type: string
      - name: countryCode
        in: header
        required: false
        description: Will be used internally by application
        schema:
          type: string
      - name: additionalFilter
        in: query
        required: false
        description: Reserve for future use. This can be used to further filter the response object. For example - if we want to retrieve only username a subscriber, then choose queryType as 'personalDetail' and additionalFilter as 'username'. Use comma seperation if case of retrive multiple attributes of an object
        schema:
          type: string
      responses:
        '200':
          description: Success
          content:
            application/json;charset=utf-8:
              schema:
                $ref: '#/components/schemas/Response_Subscriber'
        '400':
          description: Bad Request
          content:
            application/json;charset=utf-8:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Unauthorized
          content:
            application/json;charset=utf-8:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: Forbidden
          content:
            application/json;charset=utf-8:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Not Found
          content:
            application/json;charset=utf-8:
              schema:
                $ref: '#/components/schemas/Error'
        '405':
          description: Method Not allowed
          content:
            application/json;charset=utf-8:
              schema:
                $ref: '#/components/schemas/Error'
        '409':
          description: Conflict
          content:
            application/json;charset=utf-8:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: Internal Server Error
          content:
            application/json;charset=utf-8:
              schema:
                $ref: '#/components/schemas/Error'
  /linkednumber/{id}:
    get:
      operationId: retrieveLinkedNumbersById
      summary: Retrieves MTN numbers linked to an ID
      description: This operation will be used to retrieve the linked numbers associated to an identity, which will be sent to subscriber's msisdn.
      tags:
      - subscriberinfo
      parameters:
      - name: id
        description: National ID of a subscriber, which is linked to his/her subscribed MTN numbers.
        required: true
        in: path
        schema:
          type: string
      - name: certificateType
        in: query
        required: true
        description: Type of National ID
        schema:
          type: string
      - name: serviceNumber
        in: query
        required: true
        description: MSISDN of the subscriber
        schema:
          type: string
      - name: transactionId
        in: header
        required: false
        description: Unique transaction id genereted by client system. This will be used to track requests
        schema:
          type: string
      - name: countryCode
        in: header
        required: false
        description: Will be used internally by application
        schema:
          type: string
      responses:
        '200':
          description: Success
          content:
            application/json;charset=utf-8:
              schema:
                $ref: '#/components/schemas/Response_LinkedNumber'
        '400':
          description: Bad Request
          content:
            application/json;charset=utf-8:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Unauthorized
          content:
            application/json;charset=utf-8:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: Forbidden
          content:
            application/json;charset=utf-8:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Not Found
          content:
            application/json;charset=utf-8:
              schema:
                $ref: '#/components/schemas/Error'
        '405':
          description: Method Not allowed
          content:
            application/json;charset=utf-8:
              schema:
                $ref: '#/components/schemas/Error'
        '409':
          description: Conflict
          content:
            application/json;charset=utf-8:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: Internal Server Error
          content:
            application/json;charset=utf-8:
              schema:
                $ref: '#/components/schemas/Error'
components:
  schemas:
    Error:
      type: object
      title: Error
      required:
      - status
      - message
      properties:
        timestamp:
          type: string
          format: date-time
          description: Time stamp of the error
        status:
          type: string
          description: Status/Error code returned from the provider system
        error:
          type: string
          description: Status/Error description
        message:
          type: string
          description: More error details and corrective measures
        path:
          type: string
          description: the path that caused the error
    TimePeriod:
      type: object
      description: A period of time, either as a deadline (endDateTime only) a startDateTime only, or both
      properties:
        endDate:
          example: '1985-04-12'
          type: string
          description: End of the time period,represented as an [ISO8601-2004] YYYY-MM-DD format
        startDate:
          example: '1985-04-10'
          type: string
          format: date
          description: Start of the time period,represented as an [ISO8601-2004] YYYY-MM-DD format
    Address:
      type: object
      properties:
        id:
          type: string
          description: Unique identifier of the place
        city:
          type: string
          description: City that the address is in
        country:
          type: string
          description: Country that the address is in
        buildingName:
          type: string
          description: allows for buildings that have well-known names
        levelNumber:
          type: string
          description: used where a level type may be repeated e.g. BASEMENT 1, BASEMENT 2
        locality:
          type: string
          description: An area of defined or undefined boundaries within a local authority or other legislatively defined area, usually rural or semi rural in nature. [ANZLIC-STREET], or a suburb, a bounded locality within a city, town or shire principally of urban character [ANZLICSTREET]
        name:
          type: string
          description: A user-friendly name for the place, such as [Paris Store], [London Store], [Main Home]
        postcode:
          type: string
          description: descriptor for a postal delivery area, used to speed and simplify the delivery of mail (also know as zipcode)
        stateOrProvince:
          type: string
          description: the State or Province that the address is in
        streetName:
          type: string
          description: Name of the street or other street type
        streetType:
          type: string
          description: 'alley, avenue, boulevard, brae, crescent, drive, highway, lane, terrace, parade, place, tarn, way, wharf '
        streetLine1:
          type: string
        streetLine2:
          type: string
        streetLine3:
          type: string
    Response_LinkedNumber:
      type: object
      required:
      - resultCode
      - resultDescription
      properties:
        resultCode:
          type: string
          description: Result code. Example- '0000'
        resultDescription:
          type: string
          description: Result message. Example- 'Successfully processed'
        transactionId:
          type: string
          description: Transaction id returned by the provider system.
        data:
          type: object
          properties:
            linkedNumbers:
              type: array
              items:
                type: string
    SubscriberAsset:
      type: object
      required:
      - entityType
      - id
      properties:
        id:
          example: f066ffd5-e685-43bc-ad57-bfb7639decb1
          type: string
          description: Unique identifier of referenced entity within the entity/asset pair (customerId, accountId, mobile line number, imsi number, iccid,puk number, pin number ...)
        assetType:
          type: string
          description: 'product/service/resource managed entities (e.g.: mobile line subscription, video platform license, mobile equipment, device information etc). Allows identifying the specific asset within the server referenced. Supported values are implementation and application specific. Other values can be added if those listed are not enough'
        entityType:
          type: string
          description: 'Type of managed entity (e.g.: product, resource, service, customer, account)'
        createDate:
          type: string
          description: Creation date of the asset resource,represented as an [ISO8601-2004] YYYY-MM-DD format
        activationDate:
          type: string
          description: Activation date of the asset resource,represented as an [ISO8601-2004] YYYY-MM-DD format
        role:
          example: owner
          type: string
          description: 'Represents the part played by an individual in relation to being granted a set of entitlements for manageable assets (e.g.: owner, user, viewer, ...)'
    Subscriber:
      type: object
      properties:
        subscriberId:
          type: string
          description: Subscriber ID
        subscriberType:
          type: string
          description: Subscription type
          enum:
          - Prepaid
          - Postpaid
          - Hybrid
        accountNumber:
          type: string
          description: Account number of the subscriber
        serviceNumber:
          type: string
          description: Service number of the subscriber. This can be msisdn etc.
        createDate:
          type: string
          description: The date of new connection,represented as an [ISO8601-2004] YYYY-MM-DD format
        activationDate:
          type: string
          description: Activation date of new connection, represented as an [ISO8601-2004] YYYY-MM-DD format
        validFor:
          $ref: '#/components/schemas/TimePeriod'
          description: Subscription period
        status:
          $ref: '#/components/schemas/StatusType'
        description:
          type: string
          description: Blocking description etc.
        effectiveDate:
          type: string
          description: Effective date of blocking or termination etc, represented as an [ISO8601-2004] YYYY-MM-DD format
        personalDetail:
          $ref: '#/components/schemas/Subscriberinfo'
        addressDetail:
          $ref: '#/components/schemas/Address'
        identificationDetail:
          type: array
          items:
            $ref: '#/components/schemas/SubscriberIdentification'
        assetDetail:
          type: array
          items:
            $ref: '#/components/schemas/SubscriberAsset'
    SubscriberIdentification:
      type: object
      description: Represents our registration of information used as proof of identity by a subscriber (passport, national identity card, drivers license, social security number, birth certificate etc.)
      properties:
        identificationId:
          type: string
          description: Value of the chosen identification type
        identificationType:
          type: string
          description: Identification type (passport, national identity card, drivers license, social security number, birth certificate etc.)
        issuingAuthority:
          type: string
          description: 'Authority which has issued the identifier, such as: social security,town hall etc.'
        issuingDate:
          type: string
          format: date
          description: Date at which the identifier was issued
        validFor:
          $ref: '#/components/schemas/TimePeriod'
          description: The period for which the identification information is valid.
    Response_Subscriber:
      type: object
      required:
      - resultCode
      - resultDescription
      - data
      properties:
        resultCode:
          type: string
          description: Result code. Example- '0000'
        resultDescription:
          type: string
          description: Result message. Example- 'Successfully processed'
        transactionId:
          type: string
          description: Transaction id returned by the provider system.
        data:
          $ref: '#/components/schemas/Subscriber'
    Subscriberinfo:
      type: object
      required:
      - name
      properties:
        firstName:
          example: Jane
          type: string
          description: First name(s) or given name(s) of the End-User. Note that in some cultures, people can have multiple given names; all can be present, with the names being separated by space characters
        middleName:
          example: Mary
          type: string
          description: Middle name(s) of the End-User. Note that in some cultures, people can have multiple middle names; all can be present, with the names being separated by space characters. Also note that in some cultures, middle names are not used
        lastName:
          example: Doe
          type: string
          description: Last name(s) or surname(s) or of the End-User. Note that in some cultures, people can have multiple family names or no family name; all can be present, with the names being separated by space characters
        fullName:
          example: Jane Mary Doe
          type: string
          description: End-User's full name in displayable form including all name parts, possibly including titles and suffixes, ordered according to the End-User's locale and preferences
        nickname:
          example: JaneDoe
          type: string
          description: Casual name of the End-User that may or may not be the same as the given_name. For instance, a nickname value of Mike might be returned alongside a given_name value of Michael
        gender:
          example: female
          type: string
          description: End-User's gender. Values defined by this specification are female and male. Other values MAY be used when neither of the defined values are applicable
        birthdate:
          example: '1970-11-02'
          type: string
          description: End-User's birthday, represented as an [ISO8601-2004] YYYY-MM-DD format. The year MAY be 0000, indicating that it is omitted. To represent only the year, YYYY format is allowed. Note that depending on the underlying platform's date related function, providing just year can result in varying month and day, so the implementers need to take this factor into account to correctly process the dates
        email:
          example: jane.doe@email.com
          type: string
          description: End-User's preferred e-mail address. Its value MUST conform to the [RFC5322] addr-spec syntax
        emailVerified:
          default: false
          type: boolean
          description: True if the user's email has been verified.
        phoneNumber:
          example: 250897654321
          type: string
          description: End-User's preferred mobile number or telephone number. If it's mobile number, format will be mobile number prefixed with country code and (+) sign, for example, +25076854321. [E.164] is RECOMMENDED as the format if it is telephone number, for example, +1 (425) 555-1212 or +56 82) 6872400. If the telephone number contains an extension, it is RECOMMENDED that the extension be represented using the [RFC3966] extension syntax, for example, +1 (604) 555-1234;ext=5678
        phoneNumberVerified:
          default: false
          type: boolean
          description: True if the user's phone number has been verified.
        alternateNumber:
          example: 250897654543
          type: string
          description: End-User's preferred mobile number or telephone number. If it's mobile number, format will be mobile number prefixed with country code and (+) sign, for example, +25076854321. [E.164] is RECOMMENDED as the format if it is telephone number, for example, +1 (425) 555-1212 or +56 82) 6872400. If the telephone number contains an extension, it is RECOMMENDED that the extension be represented using the [RFC3966] extension syntax, for example, +1 (604) 555-1234;ext=5678
        preferredLanguage:
          example: en
          type: string
          description: End-User's locale, represented as a [RFC5646] language tag. This is typically an [ISO639-1] language code in lowercase and an [ISO3166-1] country code in uppercase, separated by a dash. For example, en-US or fr-CA. As a compatibility note, some implementations have used an underscore as the separator rather than a dash, for example, en_US
        picture:
          example: https://some.url.com/janeDoe.jpg
          type: string
          description: URL of the End-User's profile picture. This URL MUST refer to an image file (for example, a PNG, JPEG, or GIF image file), rather than to a Web page containing an image. Note that this URL SHOULD specifically reference a profile photo of the End-User suitable for displaying when describing the End-User, rather than an arbitrary photo taken by the End-User
        username:
          example: janeDoe
          type: string
          description: User ID of the subscriber
        profile:
          example: https://my.blog.com/janeDoe
          type: string
          description: URL of the End-User's profile page. The contents of this Web page SHOULD be about the End-User
        website:
          example: https://janedoe.com
          type: string
          description: URL of the End-User's Web page or blog. This Web page SHOULD contain information published by the End-User or an organization that the End-User is affiliated with
        zoneinfo:
          example: America/Los_Angeles
          type: string
          description: String from zoneinfo time zone database representing the End-User's time zone. For example, Europe/Paris or America/Los_Angeles
    StatusType:
      type: string
      enum:
      - Active
      - Inactive
      - One-Way Block
      - Two-Way Block
      - Termination
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      name: X-API-Key
      in: header
    OAuth2:
      type: oauth2
      flows:
        clientCredentials:
          scopes: {}
          tokenUrl: https://api.mtn.com/v1/oauth/access_token/accesstoken?grant_type=client_credentials