This page details the FHIR resources used across Healthcode APIs. As documented here, Healthcode APIs conform with HL7 FHIR standards. However in few cases minimal additional changes are incorporated in order to tailor the implementation to meet the needs of the UK Private Healthcare market. All such variations are also documented under relavent sections below.

Appointment

Appointment resource provides information about booking a healthcare event between patient(s), practitioner(s) and related person(s) on a specific date/time. An appointment resource may refer to a slot resource originating from a schedule resource. Additionally, an appointment resource in some cases may have direct reference to schedule resources. Appointment resources should mandatorily refer to a patient resource.

FHIR fields to create appointment

DataType	Description	FHIR Field
Reference	Reserve Slot reference of the appointment.	Appointment.identifier
CodeableConcept	Appointment type.	Appointment.appointmenttype
CodeableConcept	Service type.	Appointment.serviceType
CodeableConcept	Appointment specialty.	Appointment.specialty
StringType	Description or notes on the appointment.	Appointment.description
Date	Start date of the appointment.	Appointment.start
Date	End date of the appointment.	Appointment.end
StringType	Comments or notes on the appointment.	Appointment.comment
Array	Participants of the appointment such as practitioner, healthcareService, location (only Patient is mandatory)	Appointment.participant
Reference	Patient reference.	Appointment.participant.actor.patient
Resource	Patient resource within the appointment resource.	Appointment.contained
CodeableConcept	Participant type such as practitioner, location, etc.	Appointment.participant.type
CodeableConcept	Role of the participant.	Appointment.participant.role
Boolean	Required status of the participant.	Appointment.participant.required
CodeableConcept	Status of the participant.	Appointment.participant.status
Date	Start date-time of appointment.	Appointment.participant.startDateTime
Date	End date time of appointment.	Appointment.participant.endDateTime
Reference	Reason reference.	Appointment.reasonReference
Reference	Practitioner resource reference.	Appointment.participant.actor.Practitioner
Reference	Location resource reference.	Appointment.participant.actor.Location
Reference	Schedule reference.	Appointment.SupportingInformation.reference
Extension	Site organisation providing the services.	Appointment.Extension.site
Extension	Channel organisation who requested the appointment.	Appointment.Extension.channel
String	Business or reserve identifier of the appointment.	Appointment.Identifier.value
Extension	Referral type.	Appointment.Patient.Extension.referralType
Extension	Insurer for patient.	Appointment.Patient.Extension.insurer
Extension	Patient registration ID.	Appointment.Patient.Extension.registrationId
Extension	Authorisation number for the patient.	Appointment.Patient.Extension.authorizationno
Status	Appointment status.	Appointment.status

Below are the fields of patient resource which are supported in the appointment request and response.

DataType	Description	FHIR Field
String	Patient IF in third-party application.	Patient.id
String	Referral type.	Patient.extension
String	Insurer ID .	Patient.extension
String	Registration ID or patient’s ID recognised by the calling application.	Patient.extension
String	Authorisation number.	Patient.extension
String	Patient’s first name.	Patient.Humanname.given
String	Patient’s last name.	Patient.Humanname.family
String	Patient’s title.	Patient.Humanname.prefix
Telecom	Patient’s phone number.	Patient.Telecom.Value (Where system = ‘phone’)
Telecom	Patient’s email.	Patient.Telecom.Value (Where system = ‘email’)
String	Patient’s gender.	Patient.gender
String	Patient’s date of birth.	Patient.birthdate
Address	Patient’s address	Patient.address

We are storing only first name, last name, title, email, phone, gender, date of birth, authorisation number, insurer ID, language, referral type, referrer, registration ID and address for the Patient.

Channel

Channel is an entity of type Organization. Channels are essentially websites that publish the treatment services within ICE and allow interaction with them (typically the users of a channel are patients or people in need of practitioner appointments).

FHIR fields to create a channel

DataType	Description	FHIR Field
String	Name of organization	Organization.name
String	Alias of organization	Organization.alias
String	Contact name associated with organization	Organization.contact.name
String	Telecom values like phone, email	Organization.contact.telecom.value
Address	Address of organization	Organization.address

HealthcareService

The HealthcareService resource is used to describe a single healthcare service or category of services that are provided by an organisation at a location. Usually, healthcare service is referred to in the schedule to describe availability and configuration for defining the slots for the service.

Location

A Location describes the formally designated place (treatment site) where a service is provided by a practitioner. Locations may be consultation rooms, clinics or hospitals in some cases.

NotAvailable

NotAvailable is a custom FHIR resource introduced for managing the non-availability of a Practitioner, either at specific Locations or across all Locations/Schedules. These can either be created at the time a Schedule is created, applied to an existing Schedule or created ad-hoc without being linked to a Schedule. See “Create notAvailable” for more details.

Patient

Demographics and other administrative information about an individual receiving care or other health-related services.

Practitioner

A practitioner is a person who is directly or indirectly involved in the provisioning of healthcare.

PractitionerRole

PractionerRole describes the relationship between a practitioner and a location (treatment site). A practitioner provides services at a location. PractitionerRole as a resource should be seen as practitioner’s employment record at a specific location with information about services provided at that location.

ReserveSlot

ReserveSlot is an FHIR resource of type Slot. This is a special resource used to reserve an intended slot for booking an appointment. The endpoint of this resource is mentioned in the Search Slots section of this document.

Schedule

Schedule resources provide a container for time-slots that can be booked using an appointment. It provides the window of time (period) that slots are defined for and what type of appointments can be booked.
A schedule controls the dates and times available for the performance of a service and/or the use of a resource. One schedule applies to one service or resource since each service or resource can be reserved independently of the others. A schedule consists of configuration or definition for slots of time during which the controlled service or resource is potentially available for the provision or use.
The schedule also contains a reference to a practitioner who provides the service and the location at which the service will be performed. While its logical to refer practitionerRole resource as an actor in the schedule resource, as practitionerRole is responsible for holding the combinations of practitioner, location and HealthcareService, it’s not mandatory that all the practitioners will have their employment records maintained in Healthcode’s PPR product. To avoid any dependency on PPR products for the e-Booking subscribers, it decided to directly use practitioner, location, and HealthcareService resources in the schedule.

FHIR fields to create a schedule

Schedule resource handles the availability and non-availability of service and practitioners at a specific location.

DataType	Description	FHIR Field
Period.date	Start Date of the schedule	Schedule.planningHorizon.period.start
Period.date	End date of the schedule	Schedule.planningHorizon.period.end
CodeableConcept	Specialty of the services provided in the schedule	Schedule.specialty.codeableConcept.code
CodeableConcept	Service category	Schedule.serviceCategory.codeableConcept.code
CodeableConcept	Service type	Schedule.serviceType.codeableConcept.code
Reference	Practitioner in the schedule	Schedule.actor.Reference.value{Practitioner}
Reference	Location in the schedule	Schedule.actor.Reference.value{Location}
Reference	Healthcare Services provided in the schedule	Schedule.actor.Reference.value{HealthcareService}
extension	Site to which the schedule belongs	Schedule.Extension.referenceValue{Site}
extension	Channels that can access the slots of schedule	Schedule.Extension.referenceValue{Channel}
extension	Is walkin Slot (walkin allowed)	Schedule.Extension.valueAsBoolean
extension	Slot duration	Schedule. Extension.valueAsInt
extension	Admin interval	Schedule.Extension.valueAsInt
extension	Estimated price for slot	Schedule.Extension.valueAsDecimal
extension	Booking limit	Schedule.Extension.valueAsInt
identifier	Permission on channel “search” or “booking”	Schedule.Extension.referenceValue{Channel}.identifier.value where id=permission
StringType	Comments or notes on schedule	Schedule.comment

Schedule.planningHorizon: The ‘start’ and ‘end’ fields of the FHIR resource become the planning/scheduling period for the service and practitioner. However, within this period, the availability and non-availability of the service and practitioner are defined by the ‘availableTime’ and ‘notAvailable’ fields of the Healthcare Service resource present in Schedule resource. Detailed information about available time and not available time are described below sections.

isWalkin: This is a special extension field used to specify if the service is available on a first come first serve basis. An example of this kind of service is a physiotherapy session where patients can walk-in in a specific period as mentioned in availability.

slotDuration: This is an extension field used to specify the duration of time which should be used to break the available scheduled time as slots. These time slots are searchable and can be booked as appointments. Slots of a schedule are calculated using this parameter.

bookingLimit: This is a special extension field used to specify the concurrent number of bookings that can be made on a slot.

adminInterval: This is an extension field used to specify the minimum time interval that should be allotted after a slot time for the specific service.

HealthcareService defines the configuration that is needed to derive the slots of the schedules. Each service in the schedule can have its configuration.

DataType	Description	FHIR Field
availableTime	Availability of the service at the specific location to perform services	Healthcareservice.availableTime
string[]	Recurring days of the week where the service is available	Healthcareservice.availableTime.daysOfWeek
booleanType	Specify whether practitioner is available all day	Healthcareservice.availableTime.isAllDay
Date	Start time of the availability on the days	Healthcareservice.availableTime.startTime
Date	End time of the availability on the days	Healthcareservice.availableTime.endTime
notavailable	Non Availability of the service at the specific location to perform services	Healthcareservice.notavailabile
Period	Start and end time of the non availability on the days	Healthcareservice.notavailable.during
StringType	Reason for non availability	Healthcareservice.notavailable.description
extraDetails	Patient instructions for performing services	Schedule.contained[].HealthcareService.extraDetails
Telecom	Telecom details for online consultation of service	Schedule. contained[].HealthcareService.telecom

HealthcareService.availableTime: This is the available time within the schedule horizon period (dates) defined in the schedule resource. This time is used to calculate the slots available for booking. The ‘availableTime’ block can be repeated to add more combinations of days and times.

This ‘availableTime’ block has below fields:

daysOfWeek: This field specifies an array of recurring days of the week where the service and practitioner are available. Example: [“mon”,” wed”]

isAllDay: This Boolean field is used to specify whether the service and practitioner are available full day. The days are derived based on the daysOfWeek field. When this is set to ‘true’, the startTime and endTime fields of availableTime are ignored even if present in the request as the service is available to full day.

startTime: This is the start time from when the availability starts.

endTime: This is the end time where the availability is closed.

HealthcareService.notAvailable: This is the unavailable time of service and practitioner which will be considered while building bookable time slots. This can be holidays, leaves, or break times of the days where the service and practitioner are not available. This block can be repeated to add more dates.

NotAvailable block have below fields:

Description: This field is used to specify the reason for unavailability.

During.start: This field is used to specify the start time of unavailability.

During.end: This field is used to specify the end time of unavailability.

HealthcareService.extraDetails: This field is used to describe the instructions for patients that need to be followed for attending the service. These instructions are returned in slot search and need to be displayed to the user before booking the appointment.

HealthcareService.telecom: This is the contact information for the service.

Slot

Slot resources are used to provide time-slots that can be booked using an appointment. They do not provide any information about appointments that are available, just the time, and optionally what the time can be used for. These are effectively spaces of free/busy time.
Slots can also be marked as busy, busy -tentative, free based on the availability. Slots can be overbooked based on overbook limit configuration defined in schedule.