FIT Appointment Management API

AG-FIT 646

Release Value

Version

1.0.0

Date

2026-03-30

State

released

Description

An Appointment is an arrangement to do something or meet someone at a particular time and place. It may be created during an interaction, to resolve a customer problem, or to deliver a product order item. The Appointment Management API manages appointments and searches for available time slots based on supplied parameters.

The FIT profile is based on TMF646 Appointment Management. For FIT, PATCH and DELETE operations are not used for the Appointment and SearchTimeSlot resources.

Release notes

See Version history for the changes in this and earlier versions.

Sample use cases

Sample use cases are documented in Terminbuchung.

Managed entity resource models

Appointment

Lifecycle

Appointment lifecycle

The Appointment resource represents a booked or requested appointment.

Reference:

Resource model

resource-appointment

JSON representation sample

{
  "$schema" : "../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

SearchTimeSlot lifecycle

The SearchTimeSlot task searches for appointment slots matching the requested parameters.

Reference:

Resource model

resource-search-time-slot

JSON representation sample

{
  "$schema" : "../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

The API includes notifications for Appointment and SearchTimeSlot resources, including create, state-change, attribute-value-change, and delete events where applicable.

Reference:

Appointment state-change example

{
  "$schema" : "../schema/fit-tmf646.schema.json",
  "@type" : "AppointmentStateChangeEvent",
  "eventId" : "entstoerung-vor-8-appointment-state-change-confirmed",
  "eventTime" : "2024-02-01T11:00:00+01:00",
  "eventType" : "AppointmentStateChangeEvent",
  "event" : {
    "appointment" : {
      "@type" : "Appointment",
      "id" : "6c792dbc-abad-464d-843b-42cd7444edeb",
      "href" : "https://api.example.com/appointment/6c792dbc-abad-464d-843b-42cd7444edeb",
      "category" : "beforeFaultTicket",
      "lastUpdate" : "2024-02-01T11:00: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" : "confirmed",
      "validFor" : {
        "startDateTime" : "2024-02-02T14:00:00+01:00",
        "endDateTime" : "2024-02-02T15:00:00+01:00"
      }
    }
  }
}

SearchTimeSlot attribute-change example

{
  "$schema" : "../schema/fit-tmf646.schema.json",
  "@type" : "SearchTimeSlotAttributeValueChangeEvent",
  "eventId" : "entstoerung-vor-4-searchtimeslot-attribute-value-change",
  "eventTime" : "2024-02-01T10:31:30+01:00",
  "eventType" : "SearchTimeSlotAttributeValueChangeEvent",
  "event" : {
    "searchTimeSlot" : {
      "@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" : "inProgress",
      "stateChangeDate" : "2024-02-01T10:31:30+01:00",
      "availableTimeSlot" : [ {
        "@type" : "TimeSlot",
        "id" : "e2cd000f-4731-4036-b481-d70d7617c70e",
        "validFor" : {
          "startDateTime" : "2024-02-02T14:00:00+01:00",
          "endDateTime" : "2024-02-02T15:00:00+01:00"
        }
      }, {
        "@type" : "TimeSlot",
        "id" : "321e0c9d-1112-41ac-9251-45fe542f92",
        "validFor" : {
          "startDateTime" : "2024-02-03T08:00:00+01:00",
          "endDateTime" : "2024-02-03T12:00:00+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"
        }
      } ]
    }
  }
}

SearchTimeSlot state-change example

{
  "$schema" : "../schema/fit-tmf646.schema.json",
  "@type" : "SearchTimeSlotStateChangeEvent",
  "eventId" : "entstoerung-vor-3-searchtimeslot-state-change-in-progress",
  "eventTime" : "2024-02-01T10:31:00+01:00",
  "eventType" : "SearchTimeSlotStateChangeEvent",
  "event" : {
    "searchTimeSlot" : {
      "@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" : "inProgress",
      "stateChangeDate" : "2024-02-01T10:31:00+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"
        }
      } ]
    }
  }
}

Authentication

The API can be secured using OAuth 2.0. For service-to-service communication, use the Client Credentials flow.

Validation using the conformance profile

The conformance profile is supplied as a JSON Schema. It validates mandatory attributes, attributes that become mandatory when an optional parent is present, and conditional mandatory rules.

Download the FIT TMF646 JSON Schema

Supporting files