FIT Appointment Management API

AG-FIT 646

Release Value

Version

1.1.0

Date

2026-07-15

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.

FIT adaptations

The FIT profile is based on the TM Forum Appointment Management API.

The following operations from the base API are not used in the FIT profile:

  • PATCH and DELETE operations on Appointment.

  • PATCH and DELETE operations on SearchTimeSlot.

The complete set of supported operations and FIT-specific resource definitions is documented in the API reference.

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",
  "creationDate" : "2024-02-01T10:59:00+01:00",
  "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:30+01:00",
  "requestPostedDate" : "2024-02-01T10:30:00+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",
      "creationDate" : "2024-02-01T10:59:00+01:00",
      "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:30+01:00",
      "requestPostedDate" : "2024-02-01T10:30:00+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:30+01:00",
      "requestPostedDate" : "2024-02-01T10:30:00+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

This API is secured using OAuth 2.0. For machine-to-machine communication, it uses the Client Credentials flow. The authorization server issues an access token that the client uses to access protected API resources without sharing its credentials with the resource server.

oauthclientcredentialflow-puml

See Security schemes for the API-specific OAuth 2.0 configuration and FIT API authentication for the common authentication requirements.

Validation using the conformance profile

The conformance profile defines which attributes, structures, and constraints are applicable to the FIT implementation of TMF646. It can be used to validate Appointment and SearchTimeSlot payloads for compliance with the FIT specification.

The following artifacts are provided for validation and reference:

  • JSON Schema – machine-readable schema for automated validation of JSON payloads.

  • Excel – human-readable overview of the supported attributes, structures, and conformance requirements.

Supporting files