User Guide FIT Appointment Management API
AG-FIT 646
Release 1.0.0 (Build 912) 2026-03-27 released
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 |
|---|---|---|
| createAppointment | POST /appointment | Creates a Appointment |
| listAppointment | GET /appointment | List or find Appointment objects |
| retrieveAppointment | GET /appointment/{id} | Retrieves a Appointment by ID |
| listenToAppointmentAttributeValueChangeEvent | POST /listener/appointmentAttributeValueChangeEvent | Client listener for entity AppointmentAttributeValueChangeEvent |
| listenToAppointmentCreateEvent | POST /listener/appointmentCreateEvent | Client listener for entity AppointmentCreateEvent |
| listenToAppointmentDeleteEvent | POST /listener/appointmentDeleteEvent | Client listener for entity AppointmentDeleteEvent |
| listenToAppointmentStateChangeEvent | POST /listener/appointmentStateChangeEvent | Client listener for entity AppointmentStateChangeEvent |
| listenToSearchTimeSlotAttributeValueChangeEvent | POST /listener/searchTimeSlotAttributeValueChangeEvent | Client listener for entity SearchTimeSlotAttributeValueChangeEvent |
| listenToSearchTimeSlotStateChangeEvent | POST /listener/searchTimeSlotStateChangeEvent | Client listener for entity SearchTimeSlotStateChangeEvent |
| createSearchTimeSlot | POST /searchTimeSlot | Creates a SearchTimeSlot |
| listSearchTimeSlot | GET /searchTimeSlot | List or find SearchTimeSlot objects |
| retrieveSearchTimeSlot | GET /searchTimeSlot/{id} | Retrieves a SearchTimeSlot by ID |
Documentation for Authorization
OAuth2ClientCredentials
- Type: OAuth
-
Flow: clientCredentials
-
Token URL: https://auth.example.org/oauth2/token/
- Scopes:
- read: read objects
- write: write objects
This API can be secured using OAuth 2.0. OAuth separates the authentication provider from the resource. The authorization server issues access tokens which are used to access the protected resource. This allows consumption of the API without sharing credentials with the API provider. OAuth 2.0 is implemented in various ways using flows. The most common flow for machine-to-machine interfaces is the Client Credentials flow. This is the flow used for this API. Below is a sequence diagram illustrating the Client Credentials flow.
See also Api Authentifizierung
Sample use cases
Sample use cases can be found at Terminbuchung
Managed Entity Resource Models
Appointment
Lifecycle
AppointmentStatusType
Data type: enum of string
Valid values for the lifecycle state of the appointment
Resource model
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] | ||
| note | Note [n..m] | ||
| relatedEntity | AppointmentRelatedEntityRefOrValue [n..m] | ||
| 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/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
Lifecycle
TaskStateType
Data type: enum of string
Possible values for the state of a task are:
- acknowledged: The acknowledged state is used if a task resource has been received and has passed message and basic business validations.
- rejected: The task has been rejected during validation or processing.
- inProgress: The InProgress state is used while the task is being processed.
- done: The task has been completed and a result is available.
Resource model
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] | ||
| 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/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.