MTN Group Document API

openapi: 3.2.0
info:
  title: Mtn Group Document API
  version: '1.0'
  description: 'Operations tagged document across 2 of this provider''s published API definitions: mtn-group-document-managment.yml, mtn-group-tmf-document-management-tmf667.yml. Each path carries the servers of the definition it was published in.'
servers:
- url: https://mtn.com/tmf-api/document/v4/
- url: https://mtn.com/tmf-api/documentManagement
tags:
- name: document
paths:
  /document/{id}:
    get:
      operationId: retrieveDocument
      summary: Retrieves/Downloads a document by ID
      description: This operation retrieves a Document entity.
      tags:
      - document
      parameters:
      - name: transactionId
        description: A unique to identify each request for tracing and reporting
        required: false
        in: header
        schema:
          type: string
      - name: id
        description: Identifier of the document
        required: true
        in: path
        schema:
          type: string
      - name: queryText
        description: Rendition of document to be downloaded
        required: true
        x-example: primary
        in: query
        schema:
          type: string
      responses:
        '200':
          description: Success
          content:
            application/json;charset=utf-8:
              schema:
                allOf:
                - $ref: '#/components/schemas/ApiResponse'
                - type: object
                  properties:
                    data:
                      type: array
                      items:
                        $ref: '#/components/schemas/Document2'
        '400':
          description: Bad Request
          content:
            application/json;charset=utf-8:
              schema:
                $ref: '#/components/schemas/Error2'
        '401':
          description: Unauthorized
          content:
            application/json;charset=utf-8:
              schema:
                $ref: '#/components/schemas/Error2'
        '403':
          description: Forbidden
          content:
            application/json;charset=utf-8:
              schema:
                $ref: '#/components/schemas/Error2'
        '404':
          description: Not Found
          content:
            application/json;charset=utf-8:
              schema:
                $ref: '#/components/schemas/Error2'
        '405':
          description: Method Not allowed
          content:
            application/json;charset=utf-8:
              schema:
                $ref: '#/components/schemas/Error2'
        '409':
          description: Conflict
          content:
            application/json;charset=utf-8:
              schema:
                $ref: '#/components/schemas/Error2'
        '500':
          description: Internal Server Error
          content:
            application/json;charset=utf-8:
              schema:
                $ref: '#/components/schemas/Error2'
    patch:
      operationId: patchDocument
      summary: Updates partially a Document
      description: This operation updates partially a Document entity.
      tags:
      - document
      parameters:
      - name: id
        description: Identifier of the Document at Profile Level
        required: true
        in: path
        schema:
          type: string
      - name: profileType
        description: Identifier of the Profile Type
        required: true
        in: query
        schema:
          type: string
          enum:
          - Account Level
          - Service Level
          - Customer Level
          - Termination
      responses:
        '200':
          description: Updated
          content:
            application/json;charset=utf-8:
              schema:
                $ref: '#/components/schemas/Document'
        '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/Document_Update'
        description: The Document to be updated
        required: true
    servers:
    - url: https://mtn.com/tmf-api/document/v4/
  /document:
    get:
      operationId: listDocument
      summary: List or find document objects
      description: This operation lists or finds document entities
      tags:
      - document
      parameters:
      - name: queryText
        description: Base64 encoded query param to send query logic to WCC
        required: true
        in: query
        x-example: eFNvdXJjZVJlZ
        schema:
          type: string
      - name: transactionId
        description: A unique to identify each request for tracing and reporting
        required: false
        in: header
        schema:
          type: string
      responses:
        '200':
          description: Success
          headers:
            X-Result-Count:
              description: Actual number of items returned in the response body
              schema:
                type: integer
            X-Total-Count:
              description: Total number of items matching criteria
              schema:
                type: integer
          content:
            application/json;charset=utf-8:
              schema:
                allOf:
                - $ref: '#/components/schemas/ApiResponse'
                - type: object
                  properties:
                    data:
                      type: array
                      items:
                        $ref: '#/components/schemas/Document2'
        '400':
          description: Bad Request
          content:
            application/json;charset=utf-8:
              schema:
                $ref: '#/components/schemas/Error2'
        '401':
          description: Unauthorized
          content:
            application/json;charset=utf-8:
              schema:
                $ref: '#/components/schemas/Error2'
        '403':
          description: Forbidden
          content:
            application/json;charset=utf-8:
              schema:
                $ref: '#/components/schemas/Error2'
        '404':
          description: Not Found
          content:
            application/json;charset=utf-8:
              schema:
                $ref: '#/components/schemas/Error2'
        '405':
          description: Method Not allowed
          content:
            application/json;charset=utf-8:
              schema:
                $ref: '#/components/schemas/Error2'
        '409':
          description: Conflict
          content:
            application/json;charset=utf-8:
              schema:
                $ref: '#/components/schemas/Error2'
        '500':
          description: Internal Server Error
          content:
            application/json;charset=utf-8:
              schema:
                $ref: '#/components/schemas/Error2'
    post:
      operationId: createDocument
      summary: Creates a Document
      description: This operation creates a Document entity.
      tags:
      - document
      parameters:
      - name: transactionId
        description: A unique to identify each request for tracing and reporting
        required: false
        in: header
        schema:
          type: string
      - name: uploadType
        description: This has to be set to UPLOAD_BASE64 if the content of the document is uploaded as base64. Not required if the file is uploaded from a shared location
        required: false
        in: header
        x-example: UPLOAD_BASE64
        schema:
          type: string
      responses:
        '200':
          description: Success
          content:
            application/json;charset=utf-8:
              schema:
                $ref: '#/components/schemas/ApiResponse'
        '400':
          description: Bad Request
          content:
            application/json;charset=utf-8:
              schema:
                $ref: '#/components/schemas/Error2'
        '401':
          description: Unauthorized
          content:
            application/json;charset=utf-8:
              schema:
                $ref: '#/components/schemas/Error2'
        '403':
          description: Forbidden
          content:
            application/json;charset=utf-8:
              schema:
                $ref: '#/components/schemas/Error2'
        '405':
          description: Method Not allowed
          content:
            application/json;charset=utf-8:
              schema:
                $ref: '#/components/schemas/Error2'
        '409':
          description: Conflict
          content:
            application/json;charset=utf-8:
              schema:
                $ref: '#/components/schemas/Error2'
        '500':
          description: Internal Server Error
          content:
            application/json;charset=utf-8:
              schema:
                $ref: '#/components/schemas/Error2'
      requestBody:
        content:
          application/json;charset=utf-8:
            schema:
              $ref: '#/components/schemas/Document_Create'
        description: The Document to be created
        required: true
    servers:
    - url: https://mtn.com/tmf-api/document/v4/
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
        href:
          type: string
          format: uri
          description: Hyperlink reference
        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 Extensible name
        '@referredType':
          type: string
          description: The actual type of the target instance when needed for disambiguation.
    CharacteristicRelationship2:
      type: object
      description: Another Characteristic that is related to the current Characteristic;
      properties:
        id:
          type: string
          description: Unique identifier of the characteristic
        relationshipType:
          type: string
          description: The type of 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
    DocumentRef:
      type: object
      properties:
        refId:
          type: string
          description: Identifier of the document in other system
        href:
          type: string
          description: The URI for the object itself.
        name:
          type: string
          description: Name of the related entity.
        '@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 Extensible name
        '@referredType':
          type: string
          description: The actual type of the target instance when needed for disambiguation.
      required:
      - refId
    DocumentSpecification2:
      type: object
      description: A document specification reference
      properties:
        id:
          type: string
          description: Indentifier of the DocumentSpecification
        href:
          type: string
          description: The URI for the object itself.
        URL:
          type: string
          description: URL of the Document Specification
        name:
          type: string
          description: a String. Name of the DocumentSpecification
        version:
          type: string
          description: A string, a version of the DocumentSpecification.
        '@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
    ExternalIdentifier:
      type: object
      description: An identification of an entity that is owned by or originates in a software system different from the current system, for example a ProductOrder handed off from a commerce platform into an order handling system. The structure identifies the system itself, the nature of the entity within the system (e.g. class name) and the unique ID of the entity within the system. It is anticipated that multiple external IDs can be held for a single entity, e.g. if the entity passed through multiple systems on the way to the current system. In this case the consumer is expected to sequence the IDs in the array in reverse order of provenance, i.e. most recent system first in the list.
      required:
      - id
      properties:
        id:
          example: MC2255771199555
          type: string
          description: identification of the entity within the external system.
        href:
          type: string
          format: uri
          description: Hyperlink reference
        externalIdentifierType:
          example: ProductOrder
          type: string
          description: Type of the identification, typically would be the type of the entity within the external system
        owner:
          example: MagentoCommerce
          type: string
          description: Name of the external system that owns the entity.
        '@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 Extensible name
    CharacteristicSpecificationRelationship:
      type: object
      description: An aggregation, migration, substitution, dependency or exclusivity relationship between/among Characteristic specifications. The specification characteristic is embedded within the specification whose ID and href are in this entity, and identified by its ID.
      properties:
        characteristicSpecificationId:
          type: string
          description: Unique identifier of the characteristic within the specification
        name:
          type: string
          description: Name of the target characteristic within the specification
        parentSpecificationHref:
          type: string
          format: uri
          description: Hyperlink reference to the parent specification containing the target characteristic
        parentSpecificationId:
          type: string
          description: Unique identifier of the parent specification containing the target characteristic
        relationshipType:
          type: string
          description: Type of relationship such as aggregation, migration, substitution, dependency, exclusivity
        validFor:
          $ref: '#/components/schemas/TimePeriod'
          description: The period for which the object 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 Extensible name
    ConstraintRef:
      type: object
      description: Constraint reference. The Constraint resource represents a policy/rule applied to an entity or entity spec.
      properties:
        id:
          type: string
          description: unique identifier
        href:
          type: string
          format: uri
          description: Hyperlink reference
        name:
          type: string
          description: Name of the related entity.
        version:
          type: string
          description: constraint version
        '@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 Extensible name
        '@referredType':
          type: string
          description: The actual type of the target instance when needed for disambiguation.
      required:
      - id
    DocumentStatusType:
      type: string
      description: Possible values for the status of a Document
      enum:
      - created
      - reviewed
      - approved
      - published
      - archived
      - deleted
    RelatedParty2:
      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
        '@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.
    Characteristic2:
      type: object
      description: Describes a given characteristic of an object or entity through a name/value pair.
      required:
      - name
      - value
      properties:
        id:
          type: string
          description: Unique identifier of the characteristic
        name:
          type: string
          description: Name of the characteristic
        valueType:
          type: string
          description: Data type of the value of the characteristic
        characteristicRelationship:
          type: array
          items:
            $ref: '#/components/schemas/CharacteristicRelationship2'
        value:
          $ref: '#/components/schemas/Any'
          description: The value of the characteristic
        '@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
    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
        description:
          type: string
          description: A narrative text describing the content of the attachment. This parameter holds the shared location of the file in case uploadType is not UPLOAD_BASE64
        mimeType:
          type: string
          description: Attachment mime type such as extension file for video, picture and document
        content:
          type: string
          description: The content of the document in base64 format. Required if uploadType is UPLOAD_BASE64
        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/Quantity2'
          description: The size of the attachment.
        validFor:
          $ref: '#/components/schemas/TimePeriod2'
          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.
    RelatedEntity:
      type: object
      description: A reference to an entity, where the type of the entity is not known in advance.
      required:
      - '@referredType'
      - id
      - role
      properties:
        id:
          type: string
          description: unique identifier
        href:
          type: string
          format: uri
          description: Hyperlink reference
        name:
          type: string
          description: Name of the related entity.
        role:
          type: string
          description: The role of an entity.
        '@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 Extensible name
        '@referredType':
          type: string
          description: The actual type of the target instance when needed for disambiguation.
    Any: {}
    CharacteristicValueSpecification:
      type: object
      description: specification of a value (number or text or an object) that can be assigned to a Characteristic.
      properties:
        isDefault:
          type: boolean
          description: If true, the Boolean Indicates if the value is the default value for a characteristic
        rangeInterval:
          type: string
          description: An indicator that specifies the inclusion or exclusion of the valueFrom and valueTo attributes. If applicable, possible values are "open", "closed", "closedBottom" and "closedTop".
        regex:
          type: string
          description: A regular expression constraint for given value
        unitOfMeasure:
          type: string
          description: A length, surface, volume, dry measure, liquid measure, money, weight, time, and the like. In general, a determinate quantity or magnitude of the kind designated, taken as a standard of comparison for others of the same kind, in assigning to them numerical values, as 1 foot, 1 yard, 1 mile, 1 square foot.
        valueFrom:
          type: integer
          description: The low range value that a characteristic can take on
        valueTo:
          type: integer
          description: The upper range value that a characteristic can take on
        valueType:
          type: string
          description: A kind of value that the characteristic value can take on, such as numeric, text and so forth
        validFor:
          $ref: '#/components/schemas/TimePeriod'
          description: The period of time for which a value is applicable.
        '@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 Extensible 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
        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.
    TargetEntitySchema:
      type: object
      description: The reference object to the schema and type of target entity which is described by a specification
      required:
      - '@schemaLocation'
      - '@type'
      properties:
        '@schemaLocation':
          type: string
          description: This field provides a link to the schema describing the target entity
        '@type':
          type: string
          description: Class type of the target entity
    Error2:
      description: Used when an API throws an Error, typically with a HTTP error response-code (3xx, 4xx, 5xx)
      type: object
      required:
      - code
      - reason
      properties:
        statusCode:
          type: string
          description: A MADAPI canonical code indicating the status of the response returned.
        statusMessage:
          type: string
          description: Explanation of the reason for the error.
        supportMessage:
          type: string
          description: More details and corrective actions related to the error.
        timestamp:
          type: string
          description: Timestamp at which response is dispatched
        transactionId:
          type: string
          description: A unique to identify each request for tracing and reporting.
        path:
          type: string
          format: uri
          description: 'Indicates the url of the request sent. '
    DocumentSpecification:
      type: object
      description: 'A DocumentSpecification provides the characteristics and constraints that describe a particular type of Document. It follows the EntitySpecification pattern, so allows you to define the characteristics expected, as well as the nature of the values of those characteristics (eg: integer range [valueFrom/valueTo], regular expression or unitOfMeasure).'
      properties:
        id:
          type: string
          description: unique identifier
        href:
          type: string
          format: uri
          description: Hyperlink reference
        description:
          type: string
          description: Description of the specification
        isBundle:
          type: boolean
          description: isBundle determines whether specification represents a single specification (false), or a bundle of specifications (true).
        lastUpdate:
          type: string
          format: date-time
          description: Date and time of the last update of the specification
        name:
          example: Image Specification
          type: string
          description: The name of the DocumentSpecification
        version:
          example: 1.0.0
          type: string
          description: The version of the DocumentSpecification
        constraint:
          type: array
          items:
            $ref: '#/components/schemas/ConstraintRef'
          description: This is a list of constraint references applied to this specification
        lifecycleStatus:
          example: approved
          $ref: '#/components/schemas/DocumentSpecificationStatusType'
          description: The current lifecycle status of this DocumentSpecification
        relatedParty:
          type: array
          items:
            $ref: '#/components/schemas/RelatedParty'
          description: Parties who manage or otherwise have an interest in this specification
        specCharacteristic:
          type: array
          items:
            $ref: '#/components/schemas/CharacteristicSpecification'
          description: List of characteristics that the entity can take
        targetEntitySchema:
          $ref: '#/components/schemas/TargetEntitySchema'
          description: Pointer to a schema that defines the target entity
        validFor:
          $ref: '#/components/schemas/TimePeriod'
          description: The period for which this REST resource 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 Extensible name
    DocumentSpecificationStatusType:
      type: string
      description: Possible values for the status of a DocumentSpecification
      enum:
      - created
      - reviewed
      - approved
      - published
      - archived
      - deleted
      - received
      - verified
      - rejected
      - unindexed
    TimePeriod:
      type: object
      description: A period of time, either as a deadline (endDateTime only) a startDateTime only, or both
      properties:
        

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