MTN Group Party Interaction API

openapi: 3.2.0
info:
  title: Party Interaction API
  description: '**TMF API Reference : TMF - 683 Party Interaction**


    **Release : 19.5 - Oct 2019**


    The Party Interaction Management API provides a mechanism to manage party interactions.'
  version: 1.0.0
servers:
- url: https://api.mtn.com/partyInteraction/v1
security:
- ApiKeyAuth: []
- OAuth2: []
tags:
- name: partyInteraction
paths:
  /partyInteraction:
    post:
      operationId: createPartyInteraction
      summary: Creates a PartyInteraction
      description: This operation creates a PartyInteraction entity.
      tags:
      - partyInteraction
      responses:
        '201':
          description: Created
          content:
            application/json;charset=utf-8:
              schema:
                $ref: '#/components/schemas/PartyInteraction'
        '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/PartyInteraction_Create'
        description: The PartyInteraction to be created
        required: true
components:
  schemas:
    AttachmentRefOrValue:
      type: object
      description: An attachment by value or by reference. For AttachmentRefOrValue, the attribute type,schemaLocation and referredType are related to the contained entity and not to AttchmentRefOrValue itself
      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
          format: uri
          description: A URI to a JSON-Schema file that defines additional attributes and relationships
        '@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.
    RelatedChannel:
      type: object
      description: Related channel to another entity. May be online web, mobile app, social ,etc.
      required:
      - id
      - href
      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 channel.
        role:
          type: string
          description: Role playing by the channel.
        '@baseType':
          type: string
          description: When sub-classing, this defines the super-class
        '@schemaLocation':
          type: string
          format: uri
          description: A URI to a JSON-Schema file that defines additional attributes and relationships
        '@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.
    Note:
      type: object
      description: Extra information about a given entity
      properties:
        id:
          type: string
          description: Identifier of the note within its containing entity (may or may not be globally unique, depending on provider implementation)
        author:
          type: string
          description: Author of the note
        date:
          type: string
          format: date-time
          description: Date of the note
        text:
          type: string
          description: Text of the note
        '@baseType':
          type: string
          description: When sub-classing, this defines the super-class
        '@schemaLocation':
          type: string
          format: uri
          description: A URI to a JSON-Schema file that defines additional attributes and relationships
        '@type':
          type: string
          description: When sub-classing, this defines the sub-class entity name
    Quantity:
      type: object
      description: An amount in a given unit
      properties:
        amount:
          default: 1
          type: number
          format: float
          description: Numeric value in a given unit
        units:
          type: string
          description: Unit
    RelatedEntityRefOrValue:
      type: object
      description: A reference to an entity, where the type of the entity is not known in advance. A related entity defines a entity described by reference or by value linked to a specific entity. The polymorphic attributes @type, @schemaLocation & @referredType are related to the Entity and not the RelatedEntityRefOrValue class itself
      required:
      - role
      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
        '@baseType':
          type: string
          description: When sub-classing, this defines the super-class
        '@schemaLocation':
          type: string
          format: uri
          description: A URI to a JSON-Schema file that defines additional attributes and relationships
        '@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.
    InteractionRelationship:
      type: object
      properties:
        id:
          type: string
          description: Unique identifier of the referenced party interaction
        href:
          type: string
          description: Hyperlink to access the referenced party interaction
        relationshipType:
          type: string
          description: Type of the interaction relationship
        '@baseType':
          type: string
          description: When sub-classing, this defines the super-class
        '@schemaLocation':
          type: string
          format: uri
          description: A URI to a JSON-Schema file that defines additional attributes and relationships
        '@type':
          type: string
          description: When sub-classing, this defines the sub-class entity name
    InteractionItem:
      type: object
      properties:
        id:
          type: string
          description: Unique identifier of the interaction item
        creationDate:
          type: string
          format: date-time
          description: Date when the interaction item is created in the system
        reason:
          type: string
          description: Reason why this item is referred
        reasonCode:
          type: string
          description: Corresponding code to the reason tagged
        resolution:
          type: string
          description: Resolution of the interaction item
        prefLang:
          type: string
          description: Preffered language of the customer. It can be 'en or fr'
        csrUserName:
          type: string
          description: User name of the customer service agent
        csrUserId:
          type: string
          description: User Id of the customer service agent
        location:
          type: string
          description: this respresents the location of the customer/agent
        actionDate:
          type: string
          description: this respresents the date when the action will take place
        attachment:
          type: array
          items:
            $ref: '#/components/schemas/AttachmentRefOrValue'
        channel:
          type: array
          items:
            $ref: '#/components/schemas/RelatedChannel'
          description: 'Where the interaction took place (e.g.: web, mobile app, store, kiosk, etc.)'
        item:
          $ref: '#/components/schemas/RelatedEntityRefOrValue'
          description: RelatedEntity defines a reference to any entity. It uses polymorphism in order to let the API client know how to treat the element, as the entity type is not known beforehand.
        itemDate:
          $ref: '#/components/schemas/TimePeriod'
          description: Moment this item is referred
        note:
          type: array
          items:
            $ref: '#/components/schemas/Note'
        relatedParty:
          type: array
          items:
            $ref: '#/components/schemas/RelatedParty'
        '@baseType':
          type: string
          description: When sub-classing, this defines the super-class
        '@schemaLocation':
          type: string
          format: uri
          description: A URI to a JSON-Schema file that defines additional attributes and relationships
        '@type':
          type: string
          description: When sub-classing, this defines the sub-class entity name
    Error:
      description: Used when an API throws an Error, typically with a HTTP error response-code (3xx, 4xx, 5xx)
      type: object
      required:
      - code
      - reason
      properties:
        code:
          type: string
          description: Application relevant detail, defined in the API or a common list.
        reason:
          type: string
          description: Explanation of the reason for the error which can be shown to a client user.
        message:
          type: string
          description: More details and corrective actions related to the error which can be shown to a client user.
        status:
          type: string
          description: HTTP Error code extension
        transactionId:
          type: string
          description: A unique identifier for tracking all incoming requests
        timestamp:
          type: string
          format: date-time
          description: Error response code
        referenceError:
          type: string
          format: uri
          description: URI of documentation describing the error.
        '@baseType':
          type: string
          description: When sub-classing, this defines the super-class.
        '@schemaLocation':
          type: string
          format: uri
          description: A URI to a JSON-Schema file that defines additional attributes and relationships
        '@type':
          type: string
          description: When sub-classing, this defines the sub-class entity name.
    PartyInteraction:
      type: object
      properties:
        resultCode:
          type: string
          description: Result code. Example- '0000'
        resultDescription:
          type: string
          description: Result message. Example- 'Successfully processed'
        customerId:
          type: string
          description: MSISDN of the customer.
        id:
          type: string
          description: Unique identifier of the party interaction
        href:
          type: string
          description: Hyperlink to access the party interaction
        creationDate:
          type: string
          format: date-time
          description: Date when the interaction is created in the system
        description:
          type: string
          description: Description of the interaction
        direction:
          type: string
          description: Specifies who started the interaction. It might be the party or the enterprise exposing this API. Possible values are “inbound” and “outbound”
        reason:
          type: string
          description: Reason why the interaction happened
        status:
          type: string
          description: Status of the interaction (opened, inProgress, completed)
        statusChangeDate:
          type: string
          format: date-time
          description: Last time the status changed
        attachment:
          type: array
          items:
            $ref: '#/components/schemas/AttachmentRefOrValue'
        channel:
          type: array
          items:
            $ref: '#/components/schemas/RelatedChannel'
          description: Where the interaction took place (e.g. web, mobile app, store, kiosk, etc.)
        interactionDate:
          $ref: '#/components/schemas/TimePeriod'
          description: The period during which the interaction took place. Start and end will be different in case of a call or a store visit. They will be the same (or only one will appear) in case of a message or other momentary interactions.
        interactionItem:
          type: array
          items:
            $ref: '#/components/schemas/InteractionItem'
        interactionRelationship:
          type: array
          items:
            $ref: '#/components/schemas/InteractionRelationship'
        note:
          type: array
          items:
            $ref: '#/components/schemas/Note'
        relatedParty:
          type: array
          items:
            $ref: '#/components/schemas/RelatedParty'
        '@baseType':
          type: string
          description: When sub-classing, this defines the super-class
        '@schemaLocation':
          type: string
          format: uri
          description: A URI to a JSON-Schema file that defines additional attributes and relationships
        '@type':
          type: string
          description: When sub-classing, this defines the sub-class entity name
    PartyInteraction_Create:
      type: object
      description: '

        Skipped properties: id,href'
      required:
      - interactionDate
      - reason
      - status
      - direction
      - channel
      properties:
        creationDate:
          type: string
          format: date-time
          description: Date when the interaction is created in the system
        description:
          type: string
          description: Description of the interaction
        direction:
          type: string
          description: Specifies who started the interaction. It might be the party or the enterprise exposing this API. Possible values are “inbound” and “outbound”
        transactionId:
          type: string
          description: transactionId of the request initiated used for tracking purpose
        customerId:
          type: string
          description: MSISDN of the customer interacted with agent
        reason:
          type: string
          description: Reason why the interaction happened
        status:
          type: string
          description: Status of the interaction (opened, inProgress, completed)
        statusChangeDate:
          type: string
          format: date-time
          description: Last time the status changed
        attachment:
          type: array
          items:
            $ref: '#/components/schemas/AttachmentRefOrValue'
        channel:
          type: array
          items:
            $ref: '#/components/schemas/RelatedChannel'
          minItems: 1
          description: Where the interaction took place (e.g. web, mobile app, store, kiosk, etc.)
        interactionDate:
          $ref: '#/components/schemas/TimePeriod'
          description: The period during which the interaction took place. Start and end will be different in case of a call or a store visit. They will be the same (or only one will appear) in case of a message or other momentary interactions.
        interactionItem:
          type: array
          items:
            $ref: '#/components/schemas/InteractionItem'
        interactionRelationship:
          type: array
          items:
            $ref: '#/components/schemas/InteractionRelationship'
        note:
          type: array
          items:
            $ref: '#/components/schemas/Note'
        relatedParty:
          type: array
          items:
            $ref: '#/components/schemas/RelatedParty'
        '@baseType':
          type: string
          description: When sub-classing, this defines the super-class
        '@schemaLocation':
          type: string
          format: uri
          description: A URI to a JSON-Schema file that defines additional attributes and relationships
        '@type':
          type: string
          description: When sub-classing, this defines the sub-class entity name
    RelatedParty:
      type: object
      description: Related Entity reference. A related party defines party or party role linked to a specific entity.
      required:
      - '@referredType'
      - id
      - href
      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
        '@baseType':
          type: string
          description: When sub-classing, this defines the super-class
        '@schemaLocation':
          type: string
          format: uri
          description: A URI to a JSON-Schema file that defines additional attributes and relationships
        '@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
  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