User Guide FIT Appointment Management API
AG-FIT 646
Release 1.0.0-dev (Build 755) 2026-03-09 in review
Release notes
Please see the version history for the list of changes in the last versions.
Description
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. First, the API consists in searching free time slots based on given parameters.
TMF API Reference
TMF 646 - Appointment v4.0.0 (01-Jul-2021)
FIT Adaptations
Appointment: PATCH & DELETE are not used for FIT
SearchTimeSlot: PATCH & DELETE are not used for FIT
Sources
The source API definition can be found at fit-tmf646.yaml
Documentation for API Endpoints
All URIs are relative to https://api.example.com/tmf-api/appointmentManagement/v5
| Method | HTTP request | Description |
|---|---|---|
| createProductOrder | POST /productOrder | Creates a ProductOrder |
| listProductOrder | GET /productOrder | List or find ProductOrder objects |
| retrieveProductOrder | GET /productOrder/{id} | Retrieves a ProductOrder by ID |
| createCancelProductOrder | POST /cancelProductOrder | Creates a CancelProductOrder |
| listCancelProductOrder | GET /cancelProductOrder | List or find CancelProductOrder objects |
| retrieveCancelProductOrder | GET /cancelProductOrder/{id} | Retrieves a CancelProductOrder by ID |
| createInflightChangeProductOrder | POST /inflightChangeProductOrder | Creates an InflightChangeProductOrder |
| listInflightChangeProductOrder | GET /inflightChangeProductOrder | List or find InflightChangeProductOrder objects |
| retrieveInflightChangeProductOrder | GET /inflightChangeProductOrder/{id} | Retrieves an InflightChangeProductOrder by ID |
| listenToProductOrderCreateEvent | POST /listener/productOrderCreateEvent | Client listener for ProductOrderCreateEvent |
| listenToProductOrderStateChangeEvent | POST /listener/productOrderStateChangeEvent | Client listener for ProductOrderStateChangeEvent |
| listenToProductOrderAttributeValueChangeEvent | POST /listener/productOrderAttributeValueChangeEvent | Client listener for ProductOrderAttributeValueChangeEvent |
| listenToProductOrderInformationRequiredEvent | POST /listener/productOrderInformationRequiredEvent | Client listener for ProductOrderInformationRequiredEvent |
| listenToProductOrderJeopardyAlertEvent | POST /listener/productOrderJeopardyAlertEvent | Client listener for ProductOrderJeopardyAlertEvent |
| listenToProductOrderMilestoneEvent | POST /listener/productOrderMilestoneEvent | Client listener for ProductOrderMilestoneEvent |
| listenToCancelProductOrderStateChangeEvent | POST /listener/cancelProductOrderStateChangeEvent | Client listener for CancelProductOrderStateChangeEvent |
| listenToInflightChangeProductOrderStateChangeEvent | POST /listener/inflightChangeProductOrderStateChangeEvent | Client listener for InflightChangeProductOrderStateChangeEvent |
Documentation for Authorization
All endpoints do not require authorization.
Sample use cases
TODO API Doc: Add sample use cases and sequence diagrams for appointment creation and rescheduling.
Managed Entity Resource Models
Appointment
Field description
Appointment
Data type: Entity
An Appointment is an arrangement to do something or meet someone at a particular time, at a place (for face to face appointment) or in a contact medium (for phone appointment).
| Name | Type | Description | Example |
|---|---|---|---|
| validFor (1) | TimePeriod | ||
| @type (1) | string | When sub-classing, this defines the sub-class Extensible name | |
| category | string | Business category : intervention for example or to be more precise after SalesIntervention, orderDeliveryIntervention,... | null |
| creationDate | DateTime | Appointment creation date | null |
| description | string | Short free text describing the appointment | null |
| externalId | string | ||
| externalIdentifier | ExternalIdentifier [n..m] | ||
| lastUpdate | DateTime | Date of last appointment update | null |
| attachment | AttachmentRefOrValue [n..m] | ||
| contactMedium | ContactMedium [n..m] | ||
| note | Note [n..m] | ||
| relatedEntity | AppointmentRelatedEntityRefOrValue [n..m] | ||
| relatedParty | RelatedPartyOrPartyRole [n..m] | ||
| relatedPlace | RelatedPlaceRefOrValue | ||
| status | AppointmentStatusType | ||
| @baseType | string | When sub-classing, this defines the super-class | |
| @schemaLocation | string | A URI to a JSON-Schema file that defines additional attributes and relationships | |
| id | string | Unique identifier | 2d7ed5fd-9f62-4211-bc84-357f5f7b80f5 |
| href | URI | Hyperlink reference | https://api.example.org/resource/id |
JSON representation sample
{
"$schema" : "https://bitbucket.org/fit-api/fit-api/raw/tmf646_v1.0.0-dev/tmf646/ctk/json-schema/fit-tmf646.schema.json",
"@type" : "Appointment",
"id" : "6c792dbc-abad-464d-843b-42cd7444edeb",
"href" : "https://api.example.com/appointment/6c792dbc-abad-464d-843b-42cd7444edeb",
"category" : "beforeFaultTicket",
"lastUpdate" : "2024-02-01T10:59:00+01:00",
"relatedEntity" : [ {
"@type" : "AppointmentRelatedEntityRefOrValue",
"role" : "buyerServiceContract",
"entity" : {
"@type" : "Agreement",
"name" : "buyerServiceContract",
"engagedParty" : [ {
"@type" : "Organization",
"businessId" : "500011"
} ],
"businessId" : "500012",
"agreementType" : "buyerServiceContract"
}
}, {
"@type" : "AppointmentRelatedEntityRefOrValue",
"role" : "ordererServiceContract",
"entity" : {
"@type" : "Agreement",
"name" : "ordererServiceContract",
"engagedParty" : [ {
"@type" : "Organization",
"businessId" : "500014"
} ],
"businessId" : "500013",
"agreementType" : "ordererServiceContract"
}
}, {
"@type" : "AppointmentRelatedEntityRefOrValue",
"role" : "affectedProduct",
"entity" : {
"@type" : "ProductRef",
"id" : "922ebf01-e930-47a0-842e-059d1f188a15",
"@referredType" : "Product"
}
}, {
"@type" : "AppointmentRelatedEntityRefOrValue",
"role" : "singleContract",
"entity" : {
"@type" : "Agreement",
"name" : "singleContract",
"businessId" : "555001",
"agreementType" : "singleContract"
}
}, {
"@type" : "AppointmentRelatedEntityRefOrValue",
"role" : "searchTimeSlot",
"entity" : {
"@type" : "SearchTimeslotRef",
"id" : "158ecded-6aca-4f83-a54e-f35cc53be128",
"@referredType" : "SearchTimeslot"
}
}, {
"@type" : "AppointmentRelatedEntityRefOrValue",
"role" : "availableTimeSlot",
"entity" : {
"@type" : "AvailableTimeslotRef",
"id" : "321e0c9d-1112-41ac-9251-45fe542f92",
"@referredType" : "AvailableTimeslot"
}
} ],
"status" : "initialized",
"validFor" : {
"startDateTime" : "2024-02-02T14:00:00+01:00",
"endDateTime" : "2024-02-02T15:00:00+01:00"
}
}
SearchTimeSlot
Field description
SearchTimeSlot
Data type: Entity
This task resource is used to retrieve available time slots. One of this available time slot is after used to create or reschedule an appointment
| Name | Type | Description | Example |
|---|---|---|---|
| @type (1) | string | When sub-classing, this defines the sub-class Extensible name | |
| appointmentCategory | string | defines the category of appointment time slots are searched for | null |
| externalIdentifier | ExternalIdentifier [n..m] | ||
| requestDate | DateTime | Date when the search time slot was requested | null |
| requestPostedDate | DateTime | Date when the request was posted | null |
| searchResult | string | Result of the search time slot (success or fail for example) | null |
| state | TaskStateType | ||
| stateChangeDate | DateTime | The date and time the state changed. | null |
| stateChangeMessage | Message [n..m] | Message for the state change described as a combination of a text and a code. | [] |
| stateChangeHistory | StateChange [n..m] | ||
| availableTimeSlot | TimeSlot [n..m] | ||
| relatedEntity | SearchTimeSlotRelatedEntityRefOrValue [n..m] | ||
| relatedParty | RelatedPartyOrPartyRole | ||
| relatedPlace | RelatedPlaceRefOrValue | ||
| requestedTimeSlot | TimeSlot [n..m] | ||
| @baseType | string | When sub-classing, this defines the super-class | |
| @schemaLocation | string | A URI to a JSON-Schema file that defines additional attributes and relationships | |
| id | string | Unique identifier | 2d7ed5fd-9f62-4211-bc84-357f5f7b80f5 |
| href | URI | Hyperlink reference | https://api.example.org/resource/id |
JSON representation sample
{
"$schema" : "https://bitbucket.org/fit-api/fit-api/raw/tmf646_v1.0.0-dev/tmf646/ctk/json-schema/fit-tmf646.schema.json",
"@type" : "SearchTimeSlot",
"id" : "158ecded-6aca-4f83-a54e-f35cc53be128",
"href" : "https://api.example.com/searchTimeSlot/158ecded-6aca-4f83-a54e-f35cc53be128",
"appointmentCategory" : "beforeFaultTicket",
"requestDate" : "2024-02-01T10:30:00+01:00",
"requestPostedDate" : "2024-02-01T10:30:30+01:00",
"state" : "acknowledged",
"stateChangeDate" : "2024-02-01T10:30:15+01:00",
"relatedEntity" : [ {
"@type" : "SearchTimeSlotRelatedEntityRefOrValue",
"role" : "buyerServiceContract",
"entity" : {
"@type" : "Agreement",
"name" : "buyerServiceContract",
"engagedParty" : [ {
"@type" : "Organization",
"businessId" : "500011"
} ],
"businessId" : "500012",
"agreementType" : "buyerServiceContract"
}
}, {
"@type" : "SearchTimeSlotRelatedEntityRefOrValue",
"role" : "ordererServiceContract",
"entity" : {
"@type" : "Agreement",
"name" : "ordererServiceContract",
"engagedParty" : [ {
"@type" : "Organization",
"businessId" : "500014"
} ],
"businessId" : "500013",
"agreementType" : "ordererServiceContract"
}
}, {
"@type" : "SearchTimeSlotRelatedEntityRefOrValue",
"role" : "affectedProduct",
"entity" : {
"@type" : "ProductRef",
"id" : "922ebf01-e930-47a0-842e-059d1f188a15",
"@referredType" : "Product"
}
}, {
"@type" : "SearchTimeSlotRelatedEntityRefOrValue",
"role" : "singleContract",
"entity" : {
"@type" : "Agreement",
"name" : "singleContract",
"businessId" : "555001",
"agreementType" : "singleContract"
}
}, {
"@type" : "SearchTimeSlotRelatedEntityRefOrValue",
"role" : "optionalServices",
"entity" : {
"@type" : "ProductOffering",
"name" : "Ganzheitliche Entstoerung"
}
} ],
"requestedTimeSlot" : [ {
"@type" : "TimeSlot",
"validFor" : {
"startDateTime" : "2024-02-02T08:00:00+01:00",
"endDateTime" : "2024-02-02T12:00:00+01:00"
}
} ]
}
Notification Resource Models
Notifications related to Appointment:
- AppointmentCreateEvent
- AppointmentStateChangeEvent
- AppointmentAttributeValueChangeEvent
- AppointmentDeleteEvent
Notifications related to SearchTimeSlot:
Appointment Create Event
AppointmentCreateEvent
Data type: Event
The notification data structure
| Name | Type | Description | Example |
|---|---|---|---|
| @type (1) | string | When sub-classing, this defines the sub-class Extensible name | |
| eventId (1) | string | The identifier of the notification. | 2d7ed5fd-9f62-4211-bc84-357f5f7b80f5 |
| eventTime (1) | DateTime | Time of the event occurrence. | 2023-01-01T08:00:00+01:00 |
| eventType (1) | string | The type of the notification. | |
| event | AppointmentCreateEventPayload | ||
| @baseType | string | When sub-classing, this defines the super-class | |
| @schemaLocation | string | A URI to a JSON-Schema file that defines additional attributes and relationships | |
| description | string | An explanatory of the event. | Lorem ipsum dolor |
| timeOccurred | DateTime | The time the event occurred. | 2023-01-01T08:00:00+01:00 |
| source | EntityRef | Source Entity described by EntityRef | null |
| reportingSystem | EntityRef | Reporting System described by EntityRef | null |
JSON representation sample
No use case example available.
Appointment State Change Event
AppointmentStateChangeEvent
Data type: Event
The notification data structure
| Name | Type | Description | Example |
|---|---|---|---|
| @type (1) | string | When sub-classing, this defines the sub-class Extensible name | |
| eventId (1) | string | The identifier of the notification. | 2d7ed5fd-9f62-4211-bc84-357f5f7b80f5 |
| eventTime (1) | DateTime | Time of the event occurrence. | 2023-01-01T08:00:00+01:00 |
| eventType (1) | string | The type of the notification. | |
| event | AppointmentStateChangeEventPayload | ||
| @baseType | string | When sub-classing, this defines the super-class | |
| @schemaLocation | string | A URI to a JSON-Schema file that defines additional attributes and relationships | |
| description | string | An explanatory of the event. | Lorem ipsum dolor |
| timeOccurred | DateTime | The time the event occurred. | 2023-01-01T08:00:00+01:00 |
| source | EntityRef | Source Entity described by EntityRef | null |
| reportingSystem | EntityRef | Reporting System described by EntityRef | null |
JSON representation sample
Appointment Attribute Value Change Event
AppointmentAttributeValueChangeEvent
Data type: Event
The notification data structure
| Name | Type | Description | Example |
|---|---|---|---|
| @type (1) | string | When sub-classing, this defines the sub-class Extensible name | |
| eventId (1) | string | The identifier of the notification. | 2d7ed5fd-9f62-4211-bc84-357f5f7b80f5 |
| eventTime (1) | DateTime | Time of the event occurrence. | 2023-01-01T08:00:00+01:00 |
| eventType (1) | string | The type of the notification. | |
| event | AppointmentAttributeValueChangeEventPayload | ||
| @baseType | string | When sub-classing, this defines the super-class | |
| @schemaLocation | string | A URI to a JSON-Schema file that defines additional attributes and relationships | |
| description | string | An explanatory of the event. | Lorem ipsum dolor |
| timeOccurred | DateTime | The time the event occurred. | 2023-01-01T08:00:00+01:00 |
| source | EntityRef | Source Entity described by EntityRef | null |
| reportingSystem | EntityRef | Reporting System described by EntityRef | null |
JSON representation sample
No use case example available.
Appointment Delete Event
AppointmentDeleteEvent
Data type: Event
The notification data structure
| Name | Type | Description | Example |
|---|---|---|---|
| @type (1) | string | When sub-classing, this defines the sub-class Extensible name | |
| eventId (1) | string | The identifier of the notification. | 2d7ed5fd-9f62-4211-bc84-357f5f7b80f5 |
| eventTime (1) | DateTime | Time of the event occurrence. | 2023-01-01T08:00:00+01:00 |
| eventType (1) | string | The type of the notification. | |
| event | AppointmentDeleteEventPayload | ||
| @baseType | string | When sub-classing, this defines the super-class | |
| @schemaLocation | string | A URI to a JSON-Schema file that defines additional attributes and relationships | |
| description | string | An explanatory of the event. | Lorem ipsum dolor |
| timeOccurred | DateTime | The time the event occurred. | 2023-01-01T08:00:00+01:00 |
| source | EntityRef | Source Entity described by EntityRef | null |
| reportingSystem | EntityRef | Reporting System described by EntityRef | null |
JSON representation sample
No use case example available.
SearchTimeSlot Attribute Value Change Event
SearchTimeSlotAttributeValueChangeEvent
Data type: Event
The notification data structure
| Name | Type | Description | Example |
|---|---|---|---|
| @type (1) | string | When sub-classing, this defines the sub-class Extensible name | |
| eventId (1) | string | The identifier of the notification. | 2d7ed5fd-9f62-4211-bc84-357f5f7b80f5 |
| eventTime (1) | DateTime | Time of the event occurrence. | 2023-01-01T08:00:00+01:00 |
| eventType (1) | string | The type of the notification. | |
| event | SearchTimeSlotAttributeValueChangeEventPayload | ||
| @baseType | string | When sub-classing, this defines the super-class | |
| @schemaLocation | string | A URI to a JSON-Schema file that defines additional attributes and relationships | |
| description | string | An explanatory of the event. | Lorem ipsum dolor |
| timeOccurred | DateTime | The time the event occurred. | 2023-01-01T08:00:00+01:00 |
| source | EntityRef | Source Entity described by EntityRef | null |
| reportingSystem | EntityRef | Reporting System described by EntityRef | null |
JSON representation sample
SearchTimeSlot State Change Event
SearchTimeSlotStateChangeEvent
Data type: Event
The notification data structure
| Name | Type | Description | Example |
|---|---|---|---|
| @type (1) | string | When sub-classing, this defines the sub-class Extensible name | |
| eventId (1) | string | The identifier of the notification. | 2d7ed5fd-9f62-4211-bc84-357f5f7b80f5 |
| eventTime (1) | DateTime | Time of the event occurrence. | 2023-01-01T08:00:00+01:00 |
| eventType (1) | string | The type of the notification. | |
| event | SearchTimeSlotStateChangeEventPayload | ||
| @baseType | string | When sub-classing, this defines the super-class | |
| @schemaLocation | string | A URI to a JSON-Schema file that defines additional attributes and relationships | |
| description | string | An explanatory of the event. | Lorem ipsum dolor |
| timeOccurred | DateTime | The time the event occurred. | 2023-01-01T08:00:00+01:00 |
| source | EntityRef | Source Entity described by EntityRef | null |
| reportingSystem | EntityRef | Reporting System described by EntityRef | null |
JSON representation sample
Validation using Conformance Profile
A Conformance Profile is supplied in the form of a JSON Schema (see fit-tmf646.schema.json).
The following rules are checked:
- Mandatory attribute,
- Mandatory attribute if the optional parent attribute is present,
- Mandatory/Non-mandatory attribute, depending on further conditions
Where a resource is an input into an API (e.g. POST), Mandatory means that the attribute value must be supplied by the API consumer in the input and must not be blank or null
Where a resource is an output from an API (e.g. GET, POST), Mandatory means that the attribute value must be supplied by the API provider in the output and must not be blank or null.