Appointment Management — the OpenAPI definition published by Mplify (formerly MEF) in the MEF LSO Sonata SDK, Kylie release. LSO Sonata is the Interface Reference Point between two Service Providers (Buyer and Seller), covering inter-provider business/product automation. 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/sonata/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. Thi
# --- truncated at 32 KB (68 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/mef/refs/heads/main/openapi/mef-lso-sonata-appointment-management-openapi.yml