Appointment Management — the OpenAPI definition published by Mplify (formerly MEF) in the MEF LSO Cantata SDK, Kylie release. LSO Cantata is the Interface Reference Point between a Customer (typically an enterprise) and a Service Provider, covering the business/product layer. 6 path(s), 9 operation(s). Apache-2.0 licensed and openly downloadable from public GitHub.
openapi: 3.0.1
info:
title: Appointment Management
description: >
**This file forms part of Mplify 137.1**
**This API implements Business Requirements described in MEF 113.**
An Appointment is an arrangement to do something or meet someone at a
particular time and place. It is previously made during an interaction or
may be necessary to solve a customer problem or to deliver a product order
item. The appointment API goal is to manage an appointment with all the
necessary characteristics.
List of supported use cases:
- Search Appointment Timeslot
- Create Appointment
- Retrieve Appointment List
- Retrieve Appointment by Appointment Identifier
- Patch Appointment by Appointment Identifier
- Cancel Appointment by Appointment Identifier
- Register for Appointment Notifications
Copyright 2025 Mplify Alliance and its contributors.
This file includes content based on the TM Forum Appointment Management API
(TMF646 v4.0.0) available at
https://github.com/tmforum-apis/TMF646_AppointmentManagement, which is
licensed by the TM Forum under the Apache License version 2.0. Such content
has been modified by the Mplify Alliance and its contributors.
version: 3.0.1
servers:
- url: 'https://{serverBase}/mefApi/cantata/appointment/v3/'
variables:
serverBase:
description: The base of Seller's URL.
default: mplify.net
tags:
- name: appointment
- name: searchTimeSlot
- name: events subscription
paths:
/appointment:
get:
tags:
- appointment
summary: List or found Appointment objects
description: >
The Buyer requests a list of Appointment from the Seller based on a set
of specified filter criteria. The Seller returns a summarized list of
Appointments.
operationId: listAppointment
parameters:
- name: workOrderId
in: query
description:
A reference to a WorkOrder for which the Appointment is created.
required: false
schema:
type: string
- name: validFor.gt
in: query
description: >-
The Date and Time the Appointment is confirmed to start and end -
greater than.
required: false
schema:
type: string
format: date-time
- name: validFor.lt
in: query
description: >-
The Date and Time the Appointment is confirmed to start and end -
lower than.
required: false
schema:
type: string
format: date-time
- name: status
in: query
description: The status of the Appointment.
required: false
schema:
$ref: '#/components/schemas/AppointmentStatusType'
- name: geographicSiteId
in: query
description:
A site identifier that is associated with the Appointment.
required: false
schema:
type: string
- name: geographicAddressId
in: query
description:
An address identifier that is associated with the Appointment.
required: false
schema:
type: string
- name: buyerId
in: query
description: >-
The unique identifier of the organization that is acting as the a
Buyer. MUST be specified in the request only when the requester
represents more than one Buyer.
required: false
schema:
type: string
- name: sellerId
in: query
description: >-
The unique identifier of the organization that is acting as the
Seller. MUST be specified in the request only when responding entity
represents more than one Seller.
required: false
schema:
type: string
- name: offset
in: query
description: >-
Requested index for the start of resources to be provided in
response
required: false
schema:
type: integer
- name: limit
in: query
description: Requested number of resources to be provided in response
required: false
schema:
type: integer
format: int32
responses:
'200':
description: 'OK. (https://tools.ietf.org/html/rfc7231section-6.3.1)'
headers:
X-Pagination-Throttled:
description: >
Used to indicate that the result page was throttled to maximum
possible size and there are additional results that can be
fetched.
schema:
type: boolean
X-Total-Count:
description: >
The total number of matching records. E.g. if there are 50
matching records in total, but the request has offset=10 and
limit=10, then the X-Total-Count is 50.
schema:
type: integer
X-Result-Count:
description: The number of records included in the response
schema:
type: integer
content:
application/json;charset=utf-8:
schema:
type: array
items:
$ref: '#/components/schemas/Appointment_Find'
'400':
description: Bad Request
content:
application/json;charset=utf-8:
schema:
$ref: '#/components/schemas/Error400'
'401':
description: Unauthorized
content:
application/json;charset=utf-8:
schema:
$ref: '#/components/schemas/Error401'
'403':
description: Forbidden
content:
application/json;charset=utf-8:
schema:
$ref: '#/components/schemas/Error403'
'422':
description:
Unprocessable entity due to the business validation problems
content:
application/json;charset=utf-8:
schema:
type: array
items:
$ref: '#/components/schemas/Error422'
'500':
description: Internal Server Error
content:
application/json;charset=utf-8:
schema:
$ref: '#/components/schemas/Error500'
post:
tags:
- appointment
summary: Creates an appointment
description: >-
A request initiated by the Buyer to create a Appointment in the Seller's
system to report an Issue experienced by the Buyer
operationId: createAppointment
parameters:
- name: buyerId
in: query
description: >-
The unique identifier of the organization that is acting as the a
Buyer. MUST be specified in the request only when the requester
represents more than one Buyer.
required: false
schema:
type: string
- name: sellerId
in: query
description: >-
The unique identifier of the organization that is acting as the
Seller. MUST be specified in the request only when responding entity
represents more than one Seller.
required: false
schema:
type: string
requestBody:
description: The Appointment to be created
content:
application/json;charset=utf-8:
schema:
$ref: '#/components/schemas/Appointment_Create'
required: true
responses:
'201':
description:
'Created (https://tools.ietf.org/html/rfc7231section-6.3.2)'
content:
application/json;charset=utf-8:
schema:
$ref: '#/components/schemas/Appointment'
'400':
description: Bad Request
content:
application/json;charset=utf-8:
schema:
$ref: '#/components/schemas/Error400'
'401':
description: Unauthorized
content:
application/json;charset=utf-8:
schema:
$ref: '#/components/schemas/Error401'
'403':
description: Forbidden
content:
application/json;charset=utf-8:
schema:
$ref: '#/components/schemas/Error403'
'422':
description:
Unprocessable entity due to the business validation problems
content:
application/json;charset=utf-8:
schema:
type: array
items:
$ref: '#/components/schemas/Error422'
'500':
description: Internal Server Error
content:
application/json;charset=utf-8:
schema:
$ref: '#/components/schemas/Error500'
'/appointment/{id}':
get:
tags:
- appointment
summary: Retrieves an Appointment by ID
description: >-
The Buyer requests detailed information about a single Appointment based
on the Appointment Identifier.
operationId: retrieveAppointment
parameters:
- name: id
in: path
description:
Unique (within the Seller domain) identifier for the Appointment.
required: true
schema:
type: string
- name: buyerId
in: query
description: >-
The unique identifier of the organization that is acting as the a
Buyer. MUST be specified in the request only when the requester
represents more than one Buyer.
required: false
schema:
type: string
- name: sellerId
in: query
description: >-
The unique identifier of the organization that is acting as the
Seller. MUST be specified in the request only when responding entity
represents more than one Seller.
required: false
schema:
type: string
responses:
'200':
description: 'OK. (https://tools.ietf.org/html/rfc7231section-6.3.1)'
content:
application/json;charset=utf-8:
schema:
$ref: '#/components/schemas/Appointment'
'400':
description: Bad Request
content:
application/json;charset=utf-8:
schema:
$ref: '#/components/schemas/Error400'
'401':
description: Unauthorized
content:
application/json;charset=utf-8:
schema:
$ref: '#/components/schemas/Error401'
'403':
description: Forbidden
content:
application/json;charset=utf-8:
schema:
$ref: '#/components/schemas/Error403'
'404':
description: Not Found
content:
application/json;charset=utf-8:
schema:
$ref: '#/components/schemas/Error404'
'500':
description: Internal Server Error
content:
application/json;charset=utf-8:
schema:
$ref: '#/components/schemas/Error500'
patch:
tags:
- appointment
summary: Updates partially an Appointment
description: >-
A request by the Buyer to patch an Appointment created by the Buyer in
the Seller's system.
operationId: patchAppointment
parameters:
- name: id
in: path
description:
Unique (within the Seller domain) identifier for the Appointment.
required: true
schema:
type: string
- name: buyerId
in: query
description: >-
The unique identifier of the organization that is acting as the a
Buyer. MUST be specified in the request only when the requester
represents more than one Buyer.
required: false
schema:
type: string
- name: sellerId
in: query
description: >-
The unique identifier of the organization that is acting as the
Seller. MUST be specified in the request only when responding entity
represents more than one Seller.
required: false
schema:
type: string
requestBody:
description: The Appointment to be updated
content:
application/json;charset=utf-8:
schema:
$ref: '#/components/schemas/Appointment_Update'
required: true
responses:
'200':
description: Updated
content:
application/json;charset=utf-8:
schema:
$ref: '#/components/schemas/Appointment'
'400':
description: Bad Request
content:
application/json;charset=utf-8:
schema:
$ref: '#/components/schemas/Error400'
'401':
description: Unauthorized
content:
application/json;charset=utf-8:
schema:
$ref: '#/components/schemas/Error401'
'403':
description: Forbidden
content:
application/json;charset=utf-8:
schema:
$ref: '#/components/schemas/Error403'
'404':
description: Not Found
content:
application/json;charset=utf-8:
schema:
$ref: '#/components/schemas/Error404'
'409':
description: Not Found
content:
application/json;charset=utf-8:
schema:
$ref: '#/components/schemas/Error409'
'422':
description:
Unprocessable entity due to the business validation problems
content:
application/json;charset=utf-8:
schema:
type: array
items:
$ref: '#/components/schemas/Error422'
'500':
description: Internal Server Error
content:
application/json;charset=utf-8:
schema:
$ref: '#/components/schemas/Error500'
'/appointment/{id}/cancel':
post:
tags:
- appointment operations
summary: Cancels an Appointment
description: This operation sends a cancellation request.
operationId: cancelAppointment
parameters:
- name: id
in: path
description:
Unique (within the Seller domain) identifier for the Appointment.
required: true
schema:
type: string
- name: buyerId
in: query
description: >-
The unique identifier of the organization that is acting as the a
Buyer. MUST be specified in the request only when the requester
represents more than one Buyer.
required: false
schema:
type: string
- name: sellerId
in: query
description: >-
The unique identifier of the organization that is acting as the
Seller. MUST be specified in the request only when responding entity
represents more than one Seller.
required: false
schema:
type: string
responses:
'204':
description: Cancelled
'400':
description: Bad Request
content:
application/json;charset=utf-8:
schema:
$ref: '#/components/schemas/Error400'
'401':
description: Unauthorized
content:
application/json;charset=utf-8:
schema:
$ref: '#/components/schemas/Error401'
'403':
description: Forbidden
content:
application/json;charset=utf-8:
schema:
$ref: '#/components/schemas/Error403'
'404':
description: Not Found
content:
application/json;charset=utf-8:
schema:
$ref: '#/components/schemas/Error404'
'422':
description:
Unprocessable entity due to the business validation problems
content:
application/json;charset=utf-8:
schema:
type: array
items:
$ref: '#/components/schemas/Error422'
'500':
description: Internal Server Error
content:
application/json;charset=utf-8:
schema:
$ref: '#/components/schemas/Error500'
/searchTimeSlot:
post:
tags:
- searchTimeSlot
summary: Creates a SearchTimeSlot
description: >-
A request by the Buyer to find a set of available time slots for
scheduling or rescheduling an Appointment for a Workorder with a Seller
Technician.
operationId: createSearchTimeSlot
parameters:
- name: buyerId
in: query
description: >-
The unique identifier of the organization that is acting as the a
Buyer. MUST be specified in the request only when the requester
represents more than one Buyer.
required: false
schema:
type: string
- name: sellerId
in: query
description: >-
The unique identifier of the organization that is acting as the
Seller. MUST be specified in the request only when responding entity
represents more than one Seller.
required: false
schema:
type: string
requestBody:
description: The Appointment to be created
content:
application/json;charset=utf-8:
schema:
$ref: '#/components/schemas/SearchTimeSlot_Create'
required: true
responses:
'201':
description:
'Created (https://tools.ietf.org/html/rfc7231section-6.3.2)'
content:
application/json;charset=utf-8:
schema:
$ref: '#/components/schemas/SearchTimeSlot'
'400':
description: Bad Request
content:
application/json;charset=utf-8:
schema:
$ref: '#/components/schemas/Error400'
'401':
description: Unauthorized
content:
application/json;charset=utf-8:
schema:
$ref: '#/components/schemas/Error401'
'403':
description: Forbidden
content:
application/json;charset=utf-8:
schema:
$ref: '#/components/schemas/Error403'
'422':
description:
Unprocessable entity due to the business validation problems
content:
application/json;charset=utf-8:
schema:
type: array
items:
$ref: '#/components/schemas/Error422'
'500':
description: Internal Server Error
content:
application/json;charset=utf-8:
schema:
$ref: '#/components/schemas/Error500'
/hub:
post:
tags:
- events subscription
summary:
Allows the Buyer to register to Appointment status change notifications
description: The Buyer requests to subscribe to Appointment Notifications.
operationId: registerListener
parameters:
- name: buyerId
in: query
description: >-
The unique identifier of the organization that is acting as the a
Buyer. MUST be specified in the request only when the requester
represents more than one Buyer.
required: false
schema:
type: string
- name: sellerId
in: query
description: >-
The unique identifier of the organization that is acting as the
Seller. MUST be specified in the request only when responding entity
represents more than one Seller.
required: false
schema:
type: string
requestBody:
description:
Data containing the callback endpoint to deliver the information
content:
application/json;charset=utf-8:
schema:
$ref: '#/components/schemas/EventSubscriptionInput'
required: true
responses:
'201':
description:
'Subscribed (https://tools.ietf.org/html/rfc7231section-6.3.2)'
content:
application/json;charset=utf-8:
schema:
$ref: '#/components/schemas/EventSubscription'
'400':
description: Bad Request
content:
application/json;charset=utf-8:
schema:
$ref: '#/components/schemas/Error400'
'401':
description: Unauthorized
content:
application/json;charset=utf-8:
schema:
$ref: '#/components/schemas/Error401'
'403':
description: Forbidden
content:
application/json;charset=utf-8:
schema:
$ref: '#/components/schemas/Error403'
'422':
description:
Unprocessable entity due to the business validation problems
content:
application/json;charset=utf-8:
schema:
type: array
items:
$ref: '#/components/schemas/Error422'
'500':
description: Internal Server Error
content:
application/json;charset=utf-8:
schema:
$ref: '#/components/schemas/Error500'
'/hub/{id}':
get:
tags:
- events subscription
summary: Retrieves a Hub by ID
description: This operation retrieves a hub entity.
operationId: retrieveHub
parameters:
- name: id
in: path
description: Identifier of the Hub
required: true
schema:
type: string
- name: buyerId
in: query
description: >-
The unique identifier of the organization that is acting as the a
Buyer. MUST be specified in the request only when the requester
represents more than one Buyer.
required: false
schema:
type: string
- name: sellerId
in: query
description: >-
The unique identifier of the organization that is acting as the
Seller. MUST be specified in the request only when responding
entity represents more than one Seller.
required: false
schema:
type: string
responses:
'200':
description: Success
content:
application/json;charset=utf-8:
schema:
$ref: '#/components/schemas/EventSubscription'
'400':
description: Bad Request
content:
application/json;charset=utf-8:
schema:
$ref: '#/components/schemas/Error400'
'401':
description: Unauthorized
content:
application/json;charset=utf-8:
schema:
$ref: '#/components/schemas/Error401'
'403':
description: Forbidden
content:
application/json;charset=utf-8:
schema:
$ref: '#/components/schemas/Error403'
'404':
description: Not Found
content:
application/json;charset=utf-8:
schema:
$ref: '#/components/schemas/Error404'
'500':
description: Internal Server Error
content:
application/json;charset=utf-8:
schema:
$ref: '#/components/schemas/Error500'
delete:
tags:
- events subscription
summary: Unregister a listener
description:
The Buyer requests to unsubscribe from Appointment Notifications
operationId: unregisterListener
parameters:
- name: id
in: path
description: The id of the EventSubscription
required: true
schema:
type: string
- name: buyerId
in: query
description: >-
The unique identifier of the organization that is acting as the a
Buyer. MUST be specified in the request only when the requester
represents more than one Buyer.
required: false
schema:
type: string
- name: sellerId
in: query
description: >-
The unique identifier of the organization that is acting as the
Seller. MUST be specified in the request only when responding entity
represents more than one Seller.
required: false
schema:
type: string
responses:
'204':
description:
'Deleted (https://tools.ietf.org/html/rfc7231section-6.3.5)'
'400':
description: Bad request
content:
application/json;charset=utf-8:
schema:
$ref: '#/components/schemas/Error400'
'401':
description: Unauthorized
content:
application/json;charset=utf-8:
schema:
$ref: '#/components/schemas/Error401'
'403':
description: Forbidden
content:
application/json;charset=utf-8:
schema:
$ref: '#/components/schemas/Error403'
'404':
description: Not Found
content:
application/json;charset=utf-8:
schema:
$ref: '#/components/schemas/Error404'
'500':
description: Internal Server Error
content:
application/json;charset=utf-8:
schema:
$ref: '#/components/schemas/Error500'
components:
schemas:
Appointment:
description: >-
In the context of MEF 113 document, denotes an arrangement between the
Buyer and Seller for a Seller Technician to meet with the Buyer at a
specified time and place.
type: object
properties:
id:
description: Unique identifier of the appointment
type: string
href:
description: Unique URI used to access to the appointment resource
type: string
attachment:
description: >-
Attachments to the Appointment, such as a file, screenshot or
embedded content.
type: array
items:
$ref: '#/components/schemas/AttachmentValue'
note:
description:
Notes describing the purpose of and the results of the Appointment
type: array
items:
$ref: '#/components/schemas/Note'
relatedPlace:
description: The location of the Appointment.
$ref: '#/components/schemas/RelatedPlaceRefOrQuery'
status:
description: The state of the Appointment.
$ref: '#/components/schemas/AppointmentStatusType'
validFor:
description: >-
The Date and Time interval the Seller Technician is scheduled to
arrive at the Appointment.
$ref: '#/components/schemas/TimePeriod'
relatedContactInformation:
description: >-
Party playing a role in this Appointment. The 'role' is to specify
the type of contact as specified in MEF 113:
Appointment Place Contact (role=appointmentPlaceContact) - The site
contact(s) that the Seller Technician may need to contact in order
to get access to the Appointment Place during the Appointment. This
could be an end-user, security personnel or any authorized person
Buyer Appointment Contact (role=buyerAppointmentContact)- The Buyer
contact(s) assigned to and responsible for the Appointment.
Seller Appointment Contact (role=sellerAppointmentContact) - The
Seller contact(s) assigned to and responsible for the Appointment.
type: array
minItems: 1
items:
$ref: '#/components/schemas/RelatedContactInformation'
workOrder:
description:
A reference to a WorkOrder for which the Appointment is created.
$ref: '#/components/schemas/WorkOrderRef'
required:
- id
- relatedContactInformation
- relatedPlace
- status
- validFor
- workOrder
AppointmentStatusType:
description: |
Valid values for the lifecycle status of the appointment.
| status | MEF 113 name | Description |
| ----------------------- | ---------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `confirmed` | SCHEDULED | The Buyer has negotiated and scheduled the Appointment with the Seller. |
| `inProgress` | IN_PROGRESS | The Appointment can no longer be cancelled (point of no return), this is up to the Seller's discretion. |
| `cancelled` | CANCELLED | The Appointment was cancelled by the Buyer or the Seller determined that an Appointment was not required. This is a terminal state. |
| `missed` | MISSED | The Appointment did not take place, because of a Seller related issue. For example, no Seller Technician was available on the date of the appointment |
| `failed` | FAILED | The Appointment did not take place, because of an issue with the Buy-er. For example, Seller Technician was unable to get to the Appointment due to an incorrect location or unable to get access to the Buyer`s site. Th
# --- truncated at 32 KB (68 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/mef/refs/heads/main/openapi/mef-lso-cantata-appointment-management-openapi.yml