MTN Group Partners API

openapi: 3.2.0
info:
  title: Digital Management Partners API
  description: TM Forum Open APIs (Apache 2.0) Party Management API Provides standardized mechanism for digital partner management such as creation, update, retrieval, deletion and notification of events. Partner is an organization that has any kind of relation with the enterprise.
  version: '1.0'
servers:
- url: https://api.mtn.com/digitalPartners/v1
security:
- ApiKeyAuth: []
- OAuth2: []
tags:
- name: partners
paths:
  /partners:
    get:
      operationId: listOrganization
      summary: List or find Organization details
      description: This operation list or find Organization entities
      tags:
      - partners
      parameters:
      - required: false
        in: header
        name: transactionId
        description: Client generated Id to include for tracing requests.
        x-example: 6f0bece6-7df3-4da4-af02-5e7f16e5e6fc
        schema:
          type: string
      - required: false
        in: header
        name: targetSystem
        description: Provider system name.
        x-example: ZSmart
        schema:
          type: string
          enum:
          - ZSmart
      - required: false
        in: query
        name: idType
        description: This should be the type of ID. For eaxmple- passport, national identity card,refugee under document etc.
        schema:
          type: string
      - required: false
        in: query
        name: idValue
        description: Value of the 'idType'
        schema:
          type: string
      - required: true
        in: query
        name: customerId
        description: This can be msisdn with country code or account number etc.
        schema:
          type: string
      - required: false
        in: query
        name: customerCode
        description: Unique id generated for customer.
        schema:
          type: string
      - required: false
        in: query
        name: offset
        description: Requested index for start of resources to be provided in response
        schema:
          type: integer
      - required: false
        in: query
        name: limit
        description: Requested number of resources to be provided in response
        schema:
          type: integer
      responses:
        '200':
          description: Success
          headers:
            X-Total-Count:
              description: Total number of items matching criteria
              schema:
                type: integer
            X-Result-Count:
              description: Actual number of items returned in the response body
              schema:
                type: integer
          content:
            application/json;charset=utf-8:
              schema:
                type: object
                required:
                - result
                - data
                properties:
                  result:
                    $ref: '#/components/schemas/Result'
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/Organization'
        '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: Customer 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'
    post:
      operationId: createOrganization
      summary: Creates a Organization
      description: This operation creates a Organization entity.
      tags:
      - partners
      parameters:
      - name: transactionId
        description: A unique identifier for tracking request/response
        x-example: '32938293823'
        in: header
        schema:
          type: string
      - name: targetSystem
        in: header
        description: The target system
        schema:
          type: string
          enum:
          - COMVIVA
      responses:
        '201':
          description: Created
          content:
            application/json;charset=utf-8:
              schema:
                type: object
                required:
                - result
                - data
                properties:
                  result:
                    $ref: '#/components/schemas/Result'
                  data:
                    $ref: '#/components/schemas/Organization'
        '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'
        '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'
      requestBody:
        content:
          application/json;charset=utf-8:
            schema:
              $ref: '#/components/schemas/Organization_Create'
        description: The Organization to be created
        required: true
  /partners/{id}:
    get:
      operationId: retrieveOrganization
      summary: Retrieves a Organization by ID
      description: This operation retrieves a Organization entity. Attribute selection is enabled for all first level attributes.
      tags:
      - partners
      parameters:
      - required: true
        name: id
        in: path
        description: Identifier of the Organization
        schema:
          type: string
      - required: false
        in: header
        name: transactionId
        description: Client generated Id to include for tracing requests.
        x-example: 6f0bece6-7df3-4da4-af02-5e7f16e5e6fc
        schema:
          type: string
      - required: false
        in: header
        name: targetSystem
        description: Provider system name.
        x-example: ZSmart
        schema:
          type: string
          enum:
          - ZSmart
          - Comviva
      - name: description
        in: query
        description: Organization description
        schema:
          type: string
      - required: false
        in: query
        name: idType
        description: This should be the type of ID. For eaxmple- passport, national identity card,refugee under document etc.
        schema:
          type: string
      - required: false
        in: query
        name: idValue
        description: Value of the 'idType'
        schema:
          type: string
      - required: false
        in: query
        name: customerCode
        description: Unique id generated for customer.
        schema:
          type: string
      responses:
        '200':
          description: Success
          content:
            application/json;charset=utf-8:
              schema:
                type: object
                required:
                - result
                - data
                properties:
                  result:
                    $ref: '#/components/schemas/Result'
                  data:
                    $ref: '#/components/schemas/Organization'
        '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: Customer 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'
    patch:
      operationId: patchOrganization
      summary: Updates partially a Organization
      description: This operation updates partially a Organization entity.
      tags:
      - partners
      parameters:
      - required: true
        name: id
        in: path
        description: Identifier of the Organization
        schema:
          type: string
      - required: false
        name: transactionId
        in: header
        x-example: '88437483748374834738'
        schema:
          type: string
      responses:
        '200':
          description: Updated
          content:
            application/json;charset=utf-8:
              schema:
                type: object
                required:
                - result
                - data
                properties:
                  result:
                    $ref: '#/components/schemas/Result'
                  data:
                    $ref: '#/components/schemas/Organization'
        '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'
      requestBody:
        content:
          application/json;charset=utf-8:
            schema:
              $ref: '#/components/schemas/Organization_Update'
        description: The Organization to be updated
        required: true
components:
  schemas:
    RelatedParty:
      type: object
      description: Related Entity reference. A related party defines party or party role linked to a specific entity.
      required:
      - '@referredType'
      - id
      properties:
        id:
          type: string
          description: Unique identifier of a related entity.
        href:
          type: string
          description: Reference of the related entity.
        name:
          type: string
          description: Name of the related entity.
        role:
          type: string
          description: Role played by the related party
        description:
          type: string
        status:
          type: string
        value:
          type: string
        isRef:
          type: boolean
          description: This is a boolean indicating whether an activity should be performed or not. Eg. Activating an account, a wallet etc.
        isMinor:
          type: boolean
        validFor:
          $ref: '#/components/schemas/TimePeriod'
        '@baseType':
          type: string
          description: When sub-classing, this defines the super-class
        '@schemaLocation':
          type: string
          description: A URI to a JSON-Schema file that defines additional attributes and relationships
          format: uri
        '@type':
          type: string
          description: When sub-classing, this defines the sub-class entity name
        '@referredType':
          type: string
          description: The actual type of the target instance when needed for disambiguation.
    OrganizationParentRelationship:
      type: object
      description: Parent references of an organization in a structure of organizations.
      properties:
        relationshipType:
          type: string
          description: Type of the relationship. Could be juridical, hierarchical, geographical, functional for example.
        organization:
          $ref: '#/components/schemas/OrganizationRef'
        '@baseType':
          type: string
          description: When sub-classing, this defines the super-class
        '@schemaLocation':
          type: string
          description: A URI to a JSON-Schema file that defines additional attributes and relationships
          format: uri
        '@type':
          type: string
          description: When sub-classing, this defines the sub-class entity name
    OrganizationRef:
      type: object
      properties:
        id:
          type: string
          description: Unique identifier of a related entity.
        href:
          type: string
          description: Reference of the related entity.
        name:
          type: string
          description: Name of the related entity.
        '@baseType':
          type: string
          description: When sub-classing, this defines the super-class
        '@schemaLocation':
          type: string
          description: A URI to a JSON-Schema file that defines additional attributes and relationships
          format: uri
        '@type':
          type: string
          description: When sub-classing, this defines the sub-class entity name
        '@referredType':
          type: string
          description: The actual type of the target instance when needed for disambiguation.
      required:
      - id
    Organization_Create:
      type: object
      description: 'Organization represents a group of people identified by shared interests or purpose. Examples include business, department and enterprise. Because of the complex nature of many businesses, both organizations and organization units are represented by the same data. Skipped properties: id,href'
      required:
      - id
      - tradingName
      properties:
        isHeadOffice:
          type: boolean
          description: If value is true, the organization is the head office
        isLegalEntity:
          type: boolean
          description: If value is true, the organization is a legal entity known by a national referential.
        name:
          type: string
          description: Organization name (department name for example)
        nameType:
          type: string
          description: 'Type of the name : Co, Inc, Ltd,…'
        description:
          type: string
          description: Could be the description of the entity etc.
        organizationType:
          type: string
          description: Type of Organization (company, department...)
        tradingName:
          type: string
          description: Name that the organization (unit) trades under
        existsDuring:
          $ref: '#/components/schemas/TimePeriod'
        organizationIdentification:
          type: array
          items:
            $ref: '#/components/schemas/OrganizationIdentification'
        organizationParentRelationship:
          $ref: '#/components/schemas/OrganizationParentRelationship'
        partyCharacteristic:
          type: array
          items:
            $ref: '#/components/schemas/Characteristic'
        relatedParty:
          type: array
          items:
            $ref: '#/components/schemas/RelatedParty'
        status:
          $ref: '#/components/schemas/OrganizationStateType'
          description: Status of the organization
        '@baseType':
          type: string
          description: When sub-classing, this defines the super-class
        '@schemaLocation':
          type: string
          description: A URI to a JSON-Schema file that defines additional attributes and relationships
          format: uri
        '@type':
          type: string
          description: When sub-classing, this defines the sub-class entity name
    OrganizationStateType:
      type: string
      description: Valid values for the lifecycle state of the organization
      enum:
      - initialized
      - validated
      - closed
      - active
      - suspend
      - resume
    Result:
      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.
        sequenceNo:
          type: string
          description: A unique identifier used in tracking each request
          example: 12345
    PartyCreditProfile:
      type: object
      description: An individual might be evaluated for its worthiness and this evaluation might be based on a credit rating given by a credit agency.
      properties:
        creditAgencyName:
          type: string
          description: Name of the credit agency giving the score
        creditAgencyType:
          type: string
          description: Type of the credit agency giving the score
        ratingReference:
          type: string
          description: Reference corresponding to the credit rating
        ratingReason:
          type: string
        ratingReason2:
          type: string
        ratingReason3:
          type: string
        ratingReason4:
          type: string
        ratingScore:
          type: integer
          description: A measure of a party’s creditworthiness calculated on the basis of a combination of factors such as their income and credit history
        validFor:
          $ref: '#/components/schemas/TimePeriod'
        '@baseType':
          type: string
          description: When sub-classing, this defines the super-class
        '@schemaLocation':
          type: string
          description: A URI to a JSON-Schema file that defines additional attributes and relationships
          format: uri
        '@type':
          type: string
          description: When sub-classing, this defines the sub-class entity name
    AttachmentRefOrValue:
      type: object
      description: An attachment by value or by reference. An attachment complements the description of an element, for example through a document, a video, a picture.
      properties:
        id:
          type: string
          description: Unique identifier for this particular attachment
        href:
          type: string
          description: URI for this Attachment
        attachmentType:
          type: string
          description: Attachment type such as video, picture
        content:
          type: string
          description: The actual contents of the attachment object, if embedded, encoded as base64
        description:
          type: string
          description: A narrative text describing the content of the attachment
        mimeType:
          type: string
          description: Attachment mime type such as extension file for video, picture and document
        name:
          type: string
          description: The name of the attachment
        url:
          type: string
          description: Uniform Resource Locator, is a web page address (a subset of URI)
        size:
          $ref: '#/components/schemas/Quantity'
          description: The size of the attachment.
        validFor:
          $ref: '#/components/schemas/TimePeriod'
          description: The period of time for which the attachment is valid
        '@baseType':
          type: string
          description: When sub-classing, this defines the super-class
        '@schemaLocation':
          type: string
          description: A URI to a JSON-Schema file that defines additional attributes and relationships
          format: uri
        '@type':
          type: string
          description: When sub-classing, this defines the sub-class entity name
        '@referredType':
          type: string
          description: The actual type of the target instance when needed for disambiguation.
    DueDetail:
      type: array
      items:
        type: object
        properties:
          id:
            type: string
            description: Unique identifier. It can be customer id or account id or invoice number etc.
          description:
            type: string
            description: Description of the due detail
          validFor:
            $ref: '#/components/schemas/TimePeriod'
          dueDate:
            type: string
            format: date-time
          unpaidAmount:
            $ref: '#/components/schemas/Money'
            description: Unpaid bill amount.
          advanceAmount:
            $ref: '#/components/schemas/Money'
            description: Advance payment of the customer.
          taxExcludedAmount:
            $ref: '#/components/schemas/Money'
            description: Tax exempted amount.
          taxIncludedAmount:
            $ref: '#/components/schemas/Money'
            description: Taxable amount.
          totalDueAmount:
            $ref: '#/components/schemas/Money'
            description: total payable amount,i.e. unpaidAmount plus advance amount after taxable amount
    MemberList:
      type: array
      items:
        type: object
        properties:
          id:
            type: string
            description: ID used for unique identification
          name:
            type: string
            description: Name of the member
          serviceNumber:
            type: string
            description: Service number. In case of msisdn as service number, form will be 'countryCode+ msisdn'. example- 2507685432
          serviceType:
            type: string
            description: type of service used by member. example - GSM,Fixed Line etc.
          status:
            type: string
    OtherNameOrganization:
      type: object
      description: Keeps track of other names, for example the old name of an organization.
      properties:
        name:
          type: string
          description: Organization name (department name for example)
        nameType:
          type: string
          description: Co. , Inc. , Ltd. , Pty Ltd. , Plc; , Gmbh
        tradingName:
          type: string
          description: The name that the organization trades under
        validFor:
          $ref: '#/components/schemas/TimePeriod'
        '@baseType':
          type: string
          description: When sub-classing, this defines the super-class
        '@schemaLocation':
          type: string
          description: A URI to a JSON-Schema file that defines additional attributes and relationships
          format: uri
        '@type':
          type: string
          description: When sub-classing, this defines the sub-class entity name
    MediumCharacteristic:
      type: object
      description: Describes the contact medium characteristics that could be used to contact a party (an individual or an organization)
      properties:
        city:
          type: string
          description: The city
        contactType:
          type: string
          description: 'The type of contact, for example: phone number such as mobile, fixed home, fixed office. postal address such as shipping instalation…'
        addressType:
          type: string
          description: Type of address such as residential address, office address etc.
        placeName:
          type: string
          description: Name of village or town or place etc.
        sectorName:
          type: string
          description: Name of sector or relevant etc.
        cellName:
          type: string
          description: Name of cell number or town or place etc.
        districtName:
          type: string
          description: Name of village or town or place etc.
        streetName:
          type: string
          description: Name of the street
        street1:
          type: string
          description: Describes the street
        street2:
          type: string
        street3:
          type: string
        street4:
          type: string
        streetLine:
          type: string
        postCode:
          type: string
          description: Postcode
        stateOrProvince:
          type: string
          description: State or province
        country:
          type: string
          description: The country
        emailAddress:
          type: string
          description: Full email address in standard format
        faxNumber:
          type: string
          description: The fax number of the contact
        phoneNumber:
          type: string
          description: The primary phone number of the contact
        alternateNumber:
          type: array
          items:
            type: string
            description: List of alternate phone/contact numbers of the customer
            example:
            - '2507865432'
            - '2507235432'
            - '2507234232'
        socialNetworkId:
          type: string
          description: Identifier as a member of a social network
        title:
          type: string
          description: Prefix title of contact person
        firstName:
          type: string
          description: First name of contact person
        lastName:
          type: string
          description: Last name of contact person
        idType:
          type: string
          description: Type of ID that identifies contact person
        idNumber:
          type: string
          description: ID number of contact person
        gender:
          type: string
          description: gender of contact person
        '@baseType':
          type: string
          description: When sub-classing, this defines the super-class
        '@schemaLocation':
          type: string
          description: A URI to a JSON-Schema file that defines additional attributes and relationships
          format: uri
        '@type':
          type: string
          description: When sub-classing, this defines the sub-class entity name
    Error:
      type: object
      title: Error
      required:
      - status
      - message
      properties:
        timestamp:
          type: string
          format: date-time
          description: Error response code
        status:
          type: string
          description: HTTP Status code
        transactionId:
          type: string
          description: A unique identifier for tracking all incoming requests
        error:
          type: string
          description: Status description
        message:
          type: string
          description: More error details and corrective measures
        sequenceNo:
          type: string
          description: A unique identifier used in tracking each request
        path:
          type: string
          description: the path that caused the error
    TaxDefinition:
      type: object
      description: Reference of a tax definition. A tax is levied by an authorized tax jurisdiction. There are many different types of tax (Federal Tax levied by the US Government, State Tax levied by the State of California,…).
      properties:
        id:
          type: string
          description: Unique identifier of the tax.
        name:
          type: string
          description: Tax name.
        taxType:
          type: string
          description: Type of  the tax.
        '@baseType':
          type: string
          description: When sub-classing, this defines the super-class
        '@schemaLocation':
          type: string
          description: A URI to a JSON-Schema file that defines additional attributes and relationships
          format: uri
        '@type':
          type: string
          description: When sub-classing, this defines the sub-class entity name
        '@referredType':
          type: string
          description: The actual type of the target instance when needed for disambiguation.
    TimePeriod:
      type: object
      description: A period of time, either as a deadline (endDateTime only) a startDateTime only, or both
      properties:
        endDateTime:
          type: string
          format: date-time
          description: End of the time period, using IETC-RFC-3339 format
        startDateTime:
          type: string
          format: date-time
          description: Start of the time period, using IETC-RFC-3339 format. If you define a start, you must also define an end
    Organization_Update:
      type: object
      description: 'Organization represents a group of people identified by shared interests or purpose. Examples include business, department and enterprise. Because of the complex nature of many businesses, both organizations and organization units are represented by the same data. Skipped properties: id,href'
      required:
      - id
      properties:
        isHeadOffice:
          type: boolean
          description: If value is true, the organization is the head office
        isLegalEntity:
          type: boolean
          description: If value is true, the organization is a legal entity known by a national referential.
        name:
          type: string
          description: Organization name (department name for example)
        nameType:
          type: string
          description: 'Type of the name : Co, Inc, Ltd,…'
        organizationType:
          type: string
          description: Type of Organization (company, department...)
        tradingName:
          type: string
          description: Name that the organization (unit) trades under
        contactMedium:
          type: array
          items:
            $ref: '#/components/schemas/ContactMedium'
        creditRating:
          type: array
          items:
            $ref: '#/components/schemas/PartyCreditProfile'
        existsDuring:
          $ref: '#/components/schemas/TimePeriod'
        externalReference:
          type: array
          items:
            $ref: '#/components/schemas/ExternalReference'
        organizationChildRelationship:
          type: array
          items:
            $ref: '#/components/schemas/OrganizationChildRelationship'
        organizationIdentification:
          type: array
          items:
            $ref: '#/components/schemas/OrganizationIdentification'
     

# --- truncated at 32 KB (44 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/mtn-group/refs/heads/main/openapi/mtn-group-partners-api-openapi.yml