TM Forum Service Order API

openapi: 3.2.0
info:
  title: ServiceOrdering Service Order API
  description: '## TMF API Reference : TMF 641 - Service Ordering Management


    Version 4.1


    The Service Order API provides a standardized mechanism for managing Service Order, a type of order which can be used to place an order between internal Customer Order management system to service order management system or between a service provider and a partner and vice versa.'
  version: 4.1.0
servers:
- url: https://serverRoot/tmf-api/serviceOrdering/v4
tags:
- name: Service Order
paths:
  /serviceOrder:
    get:
      operationId: listServiceOrder
      summary: List or find ServiceOrder objects
      description: This operation list or find ServiceOrder entities
      tags:
      - Service Order
      parameters:
      - name: fields
        description: Comma-separated properties to be provided in response
        required: false
        in: query
        schema:
          type: string
      - name: offset
        description: Requested index for start of resources to be provided in response
        required: false
        in: query
        schema:
          type: integer
      - name: limit
        description: Requested number of resources to be provided in response
        required: false
        in: query
        schema:
          type: integer
      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:
                type: array
                items:
                  $ref: '#/components/schemas/ServiceOrder'
        '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'
    post:
      operationId: createServiceOrder
      summary: Creates a ServiceOrder
      description: This operation creates a ServiceOrder entity.
      tags:
      - Service Order
      responses:
        '201':
          description: Created
          content:
            application/json;charset=utf-8:
              schema:
                $ref: '#/components/schemas/ServiceOrder'
        '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/ServiceOrder_Create'
        description: The ServiceOrder to be created
        required: true
  /serviceOrder/{id}:
    get:
      operationId: retrieveServiceOrder
      summary: Retrieves a ServiceOrder by ID
      description: This operation retrieves a ServiceOrder entity. Attribute selection is enabled for all first level attributes.
      tags:
      - Service Order
      parameters:
      - name: id
        description: Identifier of the ServiceOrder
        required: true
        in: path
        schema:
          type: string
      - name: fields
        description: Comma-separated properties to provide in response
        required: false
        in: query
        schema:
          type: string
      responses:
        '200':
          description: Success
          content:
            application/json;charset=utf-8:
              schema:
                $ref: '#/components/schemas/ServiceOrder'
        '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'
    patch:
      operationId: patchServiceOrder
      summary: Updates partially a ServiceOrder
      description: This operation updates partially a ServiceOrder entity.
      tags:
      - Service Order
      parameters:
      - name: id
        description: Identifier of the ServiceOrder
        required: true
        in: path
        schema:
          type: string
      responses:
        '200':
          description: Updated
          content:
            application/json;charset=utf-8:
              schema:
                $ref: '#/components/schemas/ServiceOrder'
        '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/ServiceOrder_Update'
        description: The ServiceOrder to be updated
        required: true
    delete:
      operationId: deleteServiceOrder
      summary: Deletes a ServiceOrder
      description: This operation deletes a ServiceOrder entity.
      tags:
      - Service Order
      parameters:
      - name: id
        description: Identifier of the ServiceOrder
        required: true
        in: path
        schema:
          type: string
      responses:
        '204':
          description: Deleted
        '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:
    ExternalReference:
      type: object
      description: External reference of the individual or reference in other system
      required:
      - name
      properties:
        id:
          type: string
          description: unique identifier
        href:
          type: string
          format: uri
          description: Hyperlink reference
        externalReferenceType:
          type: string
          description: Type of the external reference
        name:
          type: string
          description: External reference name
        '@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
    ServiceStateType:
      type: string
      description: Valid values for the lifecycle state of the service
      enum:
      - feasibilityChecked
      - designed
      - reserved
      - inactive
      - active
      - terminated
    ServiceRelationship:
      type: object
      required:
      - relationshipType
      properties:
        id:
          type: string
          description: unique identifier
        href:
          type: string
          format: uri
          description: Hyperlink reference
        relationshipType:
          type: string
        service:
          $ref: '#/components/schemas/ServiceRefOrValue'
        serviceRelationshipCharacteristic:
          type: array
          items:
            $ref: '#/components/schemas/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 Extensible name
    RelatedServiceOrderItem:
      type: object
      description: RelatedServiceOrderItem (a ServiceOrder item) .The service order item which triggered service creation/change/termination.
      properties:
        id:
          type: string
          description: unique identifier
        href:
          type: string
          format: uri
          description: Hyperlink reference
        itemId:
          type: string
          description: Identifier of the order item where the service was managed
        role:
          type: string
          description: role of the service order item for this service
        serviceOrderHref:
          type: string
          description: Reference of the related entity.
        serviceOrderId:
          type: string
          description: Unique identifier of a related entity.
        itemAction:
          $ref: '#/components/schemas/OrderItemActionType'
          description: Action of the order item for this service
        '@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.
    ServiceOrderItemErrorMessage:
      type: object
      description: AServiceOrderItemErrorMessage represents an error that causes a status change in a service order item.
      properties:
        code:
          type: string
          description: error code
        message:
          type: string
          description: More details and corrective actions related to the error
        reason:
          type: string
          description: Explanation of the reason for the error
        referenceError:
          type: string
          format: uri
          description: URI of documentation describing the error
        status:
          type: string
          description: error code extension like sys-ABC-2001
        timestamp:
          type: string
          format: date-time
          description: Date when the error happened
        '@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
    OrderItemActionType:
      type: string
      description: action to be performed on the product
      enum:
      - add
      - modify
      - delete
      - noChange
    ServiceOrderItemRelationship:
      type: object
      description: Linked service order item to the one containing this attribute
      properties:
        relationshipType:
          type: string
          description: 'The type of related order item, can be: dependency if the order item needs to be not started until another order item is complete'
        orderItem:
          $ref: '#/components/schemas/ServiceOrderItemRef'
          description: A service order item in relationship with this order item
        '@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
    ServiceOrder_Update:
      type: object
      description: '

        Skipped properties: id,href,orderDate,jeopardyAlert,errorMessage,milestone,@baseType,@schemaLocation,@type,cancellationDate,cancellationReason,category,completionDate,startDate'
      properties:
        description:
          type: string
          description: A free-text description of the service order
        expectedCompletionDate:
          type: string
          format: date-time
          description: Expected delivery date amended by the provider
        externalId:
          type: string
          description: ID given by the consumer to facilitate searches
        notificationContact:
          type: string
          description: Contact attached to the order to send back information regarding this order
        priority:
          type: string
          description: Can be used by consumers to prioritize orders in a Service Order Management system
        requestedCompletionDate:
          type: string
          format: date-time
          description: Requested delivery date from the requestors perspective
        requestedStartDate:
          type: string
          format: date-time
          description: Order start date wished by the requestor
        externalReference:
          type: array
          items:
            $ref: '#/components/schemas/ExternalReference'
        note:
          type: array
          items:
            $ref: '#/components/schemas/Note'
          description: Extra-information about the order; e.g. useful to add extra delivery information that could be useful for a human process
        orderRelationship:
          type: array
          items:
            $ref: '#/components/schemas/ServiceOrderRelationship'
          description: A list of service orders related to this order (e.g. prerequisite, dependent on)
        relatedParty:
          type: array
          items:
            $ref: '#/components/schemas/RelatedParty'
          description: A list of parties which are involved in this order and the role they are playing
        serviceOrderItem:
          type: array
          items:
            $ref: '#/components/schemas/ServiceOrderItem'
          description: A list of service order items to be processed by this order
        state:
          $ref: '#/components/schemas/ServiceOrderStateType'
          description: 'State of the order: described in the state-machine diagram'
    ResourceRef:
      type: object
      properties:
        id:
          type: string
          description: unique identifier
        href:
          type: string
          format: uri
          description: Hyperlink reference
        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:
      - id
    AppointmentRef:
      type: object
      description: Refers an appointment, such as a Customer presentation or internal meeting or site visit
      properties:
        id:
          type: string
          description: The identifier of the referred appointment
        href:
          type: string
          description: The reference of the appointment
        description:
          type: string
          description: An explanatory text regarding the appointment made with a 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
      required:
      - id
    FeatureRelationship:
      type: object
      description: Configuration feature
      required:
      - name
      - relationshipType
      properties:
        id:
          type: string
          description: Unique identifier of the target feature.
        name:
          type: string
          description: This is the name of the target feature.
        relationshipType:
          type: string
          description: This is the type of the feature relationship.
        validFor:
          $ref: '#/components/schemas/TimePeriod'
          description: The period for which this feature relationship is valid.
    ServiceOrderStateType:
      type: string
      description: Possible values for the state of the order
      enum:
      - acknowledged
      - rejected
      - pending
      - held
      - inProgress
      - cancelled
      - completed
      - failed
      - partial
      - assessingCancellation
      - pendingCancellation
    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 Extensible name
        '@referredType':
          type: string
          description: The actual type of the target instance when needed for disambiguation.
    ServiceOrderRelationship:
      type: object
      description: Linked service order to the one containing this attribute
      required:
      - id
      - relationshipType
      properties:
        id:
          type: string
          description: The id of the related order
        href:
          type: string
          description: A hyperlink to the related order
        relationshipType:
          type: string
          description: 'The type of related order, such as: [dependency] if the order needs to be [not started] until another order item is complete (a service order in this case) or [cross-ref] to keep track of the source order (a productOrder)'
        '@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 entity type of the related order
    CharacteristicRelationship:
      type: object
      description: Another Characteristic that is related to the current Characteristic;
      properties:
        id:
          type: string
          description: Unique identifier of the characteristic
        href:
          type: string
          format: uri
          description: Hyperlink reference
        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 Extensible name
    Characteristic:
      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/CharacteristicRelationship'
        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 Extensible name
    ServiceOrder:
      type: object
      properties:
        id:
          type: string
          description: ID created on repository side
        href:
          type: string
          description: Hyperlink to access the order
        cancellationDate:
          type: string
          format: date-time
          description: 'Date when the order is cancelled. This is used when order is cancelled. '
        cancellationReason:
          type: string
          description: 'Reason why the order is cancelled. This is used when order is cancelled. '
        category:
          type: string
          description: 'Used to categorize the order, useful for the OM system, such as: Broadband, TVOption'
        completionDate:
          type: string
          format: date-time
          description: Effective delivery date amended by the provider
        description:
          type: string
          description: A free-text description of the service order
        expectedCompletionDate:
          type: string
          format: date-time
          description: Expected delivery date amended by the provider
        externalId:
          type: string
          description: ID given by the consumer to facilitate searches
        notificationContact:
          type: string
          description: Contact attached to the order to send back information regarding this order
        orderDate:
          type: string
          format: date-time
        priority:
          type: string
          description: Can be used by consumers to prioritize orders in a Service Order Management system
        requestedCompletionDate:
          type: string
          format: date-time
          description: Requested delivery date from the requestors perspective
        requestedStartDate:
          type: string
          format: date-time
          description: Order start date wished by the requestor
        startDate:
          type: string
          format: date-time
          description: Date when the order was started for processing
        errorMessage:
          type: array
          items:
            $ref: '#/components/schemas/ServiceOrderErrorMessage'
          description: the error(s) cause an order status change
        externalReference:
          type: array
          items:
            $ref: '#/components/schemas/ExternalReference'
        jeopardyAlert:
          type: array
          items:
            $ref: '#/components/schemas/ServiceOrderJeopardyAlert'
          description: A list of jeopardy alerts related to this order
        milestone:
          type: array
          items:
            $ref: '#/components/schemas/ServiceOrderMilestone'
          description: A list of milestones related to this order
        note:
          type: array
          items:
            $ref: '#/components/schemas/Note'
          description: Extra-information about the order; e.g. useful to add extra delivery information that could be useful for a human process
        orderRelationship:
          type: array
          items:
            $ref: '#/components/schemas/ServiceOrderRelationship'
          description: A list of service orders related to this order (e.g. prerequisite, dependent on)
        relatedParty:
          type: array
          items:
            $ref: '#/components/schemas/RelatedParty'
          description: A list of parties which are involved in this order and the role they are playing
        serviceOrderItem:
          type: array
          items:
            $ref: '#/components/schemas/ServiceOrderItem'
          description: A list of service order items to be processed by this order
        state:
          $ref: '#/components/schemas/ServiceOrderStateType'
          description: 'State of the order: described in the state-machine diagram'
        '@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
    Feature:
      type: object
      description: Configuration feature.
      required:
      - featureCharacteristic
      - name
      properties:
        id:
          type: string
          description: Unique identifier of the feature.
        isBundle:
          type: boolean
          description: True if this is a feature group. Default is false.
        isEnabled:
          type: boolean
          description: True if this feature is enabled. Default is true.
        name:
          type: string
          description: This is the name for the feature.
        constraint:
          type: array
          items:
            $ref: '#/components/schemas/ConstraintRef'
          description: This is a list of feature constraints.
        featureCharacteristic:
          type: array
          items:
            $ref: '#/components/schemas/Characteristic'
          minItems: 1
          description: This is a list of Characteristics for a particular feature.
        featureRelationship:
          type: array
          items:
            $ref: '#/components/schemas/FeatureRelationship'
    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 c

# --- truncated at 32 KB (55 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/tm-forum/refs/heads/main/openapi/tm-forum-service-order-api-openapi.yml