Disclaimer: This is a draft specification document only and may not be relied upon for any purpose other than to review the current state of the development of this draft document. Healthcode reserves the right to change, add, delete any or all portions, or otherwise modify this draft document at any time without notice.  You should not and may not rely upon this draft document in any way, including but not limited to the development of any products or services.  Implementation of this draft document is done at your own risk.  Healthcode retains the copyright of this draft document, the website, and the materials and information contained therein, with all rights reserved by Healthcode.

Introduction

The ICE service (Integrated Channel Exchange) is intended to provide practitioners, hospitals and clinics with a 24 x 7 x 365^* global distribution system (GDS) for managing patient appointments. ^{(*Subject to Healthcode SLAs)}

This document explains the typical workflow for each functionality and the related APIs that support them.

The basic premise of the ICE system is this:

1. Service providers (practitioners) can publish their availability into a central repository of availability or Global Distribution System (GDS), which records details of :
   • Who the provider is (their name, contact details, their specialty/sub-specialty)
   • Their availability (which locations they can see patients at, on which days and at which times)
   • Which services that they are able to provide. (types of consultation, treatment, etc)
2. Other parties (channels) can then query the data repository to match a patient’s requirements with the correct type of practitioner for the correct service, at a convenient time and location.
3. Once a match has been made, an appointment can be booked, and the details can be pulled back into the practitioner’s diary.
4. If the appointment is cancelled or amended, the practitioner can provide details back to the party who made the booking. Equally, confirmation can be sent that the patient attended the appointment.

It is important to note that the ICE service does NOT make recommendations as to the suitability of practitioners or hospitals, nor does it make recommendations as to the suitability of available appointments, services and treatments. These decisions are solely down to the third-party integrators as to which specialties/sub-specialties/services they have requested, and ICE will return results that match those search requests.

All interactions with ICE are live (via REST APIs) to prevent double bookings.

Onboarding

Before starting to integrate with ICE, your organisation will need to register its interest with Healthcode. This kicks off the onboarding process, which will include you being issued with the necessary security credentials to access the ICE APIs in a sandbox (UAT) environment. Once development has been completed and you can demonstrate that you conform to our technical requirements, credentials for accessing the production environment will be issued.

Healthcode APIs, security, and authentication

Please refer to the API Overview page for information on how to integrate with Healthcode APIs.

All Healthcode APIs require authentication using credentials supplied during the onboarding process. Refer to the instructions here for details.

FHIR

Similar to all other Healthcode APIs, all ICE APIs conform to FHIR standard, with reference datasets and extensions tailored for the UK private healthcare sector.

HL7 FHIR allows for 2 typical workflows that occur with appointments: Outlook Style – Community and Hospital Scheduling – Clinical. Healthcode ICE currently supports the Outlook Style workflow, where appointments are booked at specific times, rather than Hospital Scheduling which is more of a queue-like process without actual time.

HL7 FHIR also allows for appointments to have numerous different statuses (AppointmentStatus). As ICE appointments a booked directly into a diary, statuses such as “proposed”, “pending” and “waitlist” are not supported. All new appointments automatically have a status of “booked”, and can be subsequently updated (by either the practitioner or hospital) to “arrived”, “fulfilled” or “noshow”. The FHIR status “checked-in” is not currently supported, as “arrived” can be used in its place.

Reference data

The majority of the reference tables used within the ICE system (such as professions, specialties, treatment sites etc.) are standard Healthcode Reference/Master Data APIs.  Additionally, some PPR APIs may be used to augment the ICE data or FHIR’s own APIs may be called for common lookup lists (additional subscription required).

It is strongly recommended that all reference tables be cached locally. This decreases bandwidth and increases response times. Healthcode APIs support the _since parameter, allowing you to return records which have been added since your last synchronisation.

Reference tables should be refreshed periodically, either with a complete refresh or by querying changes made since a given date.

ICE is tightly coupled with The PPR and having a PPR profile is a prerequisite for a practitioner to publish their booking schedules. Their PPR record defines which locations they are permitted to work from and stores details such as their profession, specialties and sub-specialties, and age range of patients that they are qualified to see. However, PPR data is separate from ICE

The table below provides a listing of the different data entities referenced within the request data structure for the create schedule API and details of the source from which the master dataset for the same can be retrieved.

Field Name	FHIR Field	Field Source
Channel	Schedule.extension.valueReference	GET: {ice_URL}/schedule/channel/search?location:not={locationId}&site:not={siteId}&practitioner:not={practitionerId}
Channel permissions	Schedule.extension.valueReference.Identifier.value	{ice_URL}/valueset/channelPermissions
Location	Schedule.actor.reference ( WHERE reference type is Location)	GET: {ice_URL}/schedule/location/search?site={siteId}
Practitioner	Schedule.actor.reference ( WHERE reference type is Practitioner)	GET: {ice_URL}/schedule/practitioner/search?site={siteId} Use practitioner search endpoint in Booking rather than the one in PPR.
specialty	Schedule.specialty	{ref_URL}/valueset/specialty
sub-specialty	Schedule.specialty	{ref_URL}/valueset/subspecialty
serviceType	Schedule.serviceType	{ref_URL}/valueset/service-type/ISC
serviceCategory	Schedule.serviceCategory	{ref_URL}/valueset/service-category/ISC
Insurer	Patient.extension.insurer	{ref_URL}/organization?type=ins

Channel: Channel is the third-party organisation that can search and book the visible slots of the schedule, unless permissions have been denied. Refer to the Custom FHIR Resources section of this document for more information about channels and their blocking permissions.

ChannelPermissions: Schedule creators (diary owners) can choose to restrict the access permission assigned to a given schedule. If no restrictions are specified (default) then ALL channels can both search for available slots within the schedule and make bookings into it. Restrictions can be added to prevent one or more channels from making bookings and/or searching. (By blocking a channel from being able to search, you are also automatically blocking them from making bookings.)

• blockPermission : search prevents searching, and by implications also prevents booking
• blockPermission : book allows searching but prevents booking
• When no blockPermission records are specified, all channels are permitted to both search and book.

Each channel can have a maximum of ONE blockPermission per schedule as there is no reason to have both search and book permissions at the same time.

Below are examples of setting restrictions on channels.

1. Restrict a channel from being able to search slots. If searching is blocked, then booking is, by implication, also blocked as the channel will be unable to view the available slots.

Add the below example snippet to the schedule request JSON as an extension.

{
   "url":"{ref_URL}/extension/channel",
   "valueReference":{
      "reference":"Channel/{channel_id}",
      "identifier":{
         "id":"blockPermission",
         "value":"search"
      }
   }
}

2. Allow the channel to search for slots but restrict them from being able to make bookings into the searched slots.

Add the below example snippet to the schedule request JSON as an extension.

{
   "url":"{ref_URL}/extension/channel",
   "valueReference":{
      "reference":"Channel/{channel_id}",
      "identifier":{
         "id":"blockPermission",
         "value":"booking"
      }
   }
}

Location: This is the treatment site or the location where the practitioner will perform the service. It is always a physical address that has been allocated a unique HP number connected to the Healthcode Site.

• If you don’t know the HP number of a location, use the Location Lookup API.
• The ICE service will accept only locations recorded in the practitioner’s PPR profile. If a practitioner attempts to publish a schedule for a location that is NOT on their PPR profile, the process will fail, and an error will be returned. The only exceptions to this are locations defined by Healthcode as being “virtual” locations; these can be used for remote consultations without being included in the PPR profile.

Practitioner: A practitioner is the person who will be performing the services in the scheduled period. The practitioner must have a PPR profile set up, which allocates them their unique SP reference number, and the profile must be in active status (i.e. contains all necessary information and validated by Healthcode).

• If you have your OWN reference numbers for practitioners or you do not know the SP reference for a practitioner, you can make a call to the Search Slot API using the “last-name” and “first-name” parameters with the “first-available-slot-only” flag to generate a list of active ICE practitioners matching that name, including their SP.

schedule.specialty: This is the specialty of the service present in the schedule. This specialty is a searchable parameter used for searching slots.

Please note the spelling of specialty and not speciality with a second i.

• As FHIR also allows for different coding systems, the “specialty” field can be used to store specialties AND sub-specialties simply by using a different coding system for each. The coding system for the main specialties is “practitioner-specialty”, whereas the coding system for sub-specialties is “practitioner-subspecialty”. Both of these codesets are defined and maintained by Healthcode. A schedule can contain any number or combination or specialties/sub-specialties.

schedule.serviceCategory: This is the category of the service present in the schedule, not the actual service itself.

Schedule.serviceType: This is the actual healthcare service that will be available during the scheduled period, (such as Initial Consultation, Follow-up Consultation, Blood Test, etc.)

NotAvailable: When creating a schedule, it can optionally contain one or more NotAvailable records, specifying periods of time which are unavailable for booking. For example, a 09:00 to 16:00 schedule may contain tea breaks at 10:30-10:45 and 15:00-15:15 and a lunch break 13:00-14:00, or longer periods for holidays. NotAvailable periods can also be added AFTER the schedule has been created using Create NotAvailable API.

Shared Diary Ownership

It is important to understand that the ownership of a diary is shared between the practitioner and the clinic/hospital where the appointment is being held. This “shared access” means that both parties have equal permissions to the diary, and so both can manage schedules and appointments. Where this or other documents refer to “diary owner” or “diary owners”, this refers to both the practitioner and the clinic/hospital.

General Advice to System Integrators

• • The Discovery Document must be used to find the current API endpoints for each environment (UAT or Production) as these may change without notice
  • Whilst Healthcode aims to provide an uninterrupted service for ICE, integrating systems must account for system outages that may be outside of Healthcode’s control.

• • Integrating systems must never instruct the end-user to contact Healthcode for support. All support should be provided by the integrating system supplier, and if they can not resolve the issue, the supplier should contact Healthcode. The only exception to this is if a practitioner has issues accessing their PPR record, in which case they can contact Healthcode Support in the usual way.

• • Wherever possible, system integrators should submit their own UNIQUE “identifier”, such as a GUID, when creating data (such as publishing schedules, booking appointments, adding unavailability, etc). This will allow the records to be retrieved even if the automatically generated ICE identifier is changed. FHIR refers to these as “Business Identifiers” as they belong to a business and can follow a resource even when the “instance identifier” is changed.  For example, if an appointment is rescheduled, its ICE “instance identifier” may change, but the “business identifiers” will be retained.

Example workflows for booking portals

Booking an appointment without using The PPR

The following steps set out the high-level integration flow from booking portals.

• • Prompt the user for any search criteria. These includes (but aren’t limited to):
    Date/Time: date range, days of the week, available times
    Location: either one or more hospital ID codes, or geographic coordinates and a search radius (ie, within 15 miles of Staines)
    Practitioner: One or more practitioner ID codes, all practitioners for a given specialty or sub-specialty, practitioner name, practitioner gender
    Service required (or service category)
    Estimated price of service
  • In-Person (Face-to-face) or Remote (video consultation)

• • Query ICE using relevant parameters (date/time/location, etc) via the Search Slots API. If needing to search availability for a specific practitioner or a known group of practitioners, specify a single practitioner ID or a list of IDs within the request. If no practitioner ID is specified, then ALL practitioners matching the search criteria are included.
    • • Narrower search parameters give faster results. Preferably limit the search to a week or two, a single location, or a smaller search radius. These can always be increased on subsequent searches if not enough results are returned. (The near search parameter can be used to specify the longitude/latitude and search radius for the desired location).
    • • Using additional search parameters such as first-available-slot-only, which will return only the first available slot for each practitioner at each location, can be added to further limit the number of results and, therefore, increase the speed of the search.
    • • Be careful when using estimated-price as a search criterion, as it will exclude results if the practitioner has not published an estimated price. It is also strongly recommended to use the “ap” (approximate) prefix, as this returns estimated prices in a range of +/-10%
    • • Use paging to limit the number of results returned to 50 or so at a time, then request the next page of results if none are suitable.

• • Display and allow the user to select their preferred appointment slot. Reminder: All dates/times are recorded in UTC time format. The calling application must convert these times into local time when displaying them to the user, taking into account changes for Daylight Saving Time etc. 

• • Certain information MUST be presented to the patient IN FULL before allowing a booking:
    • • The schedule “comment” field, as this gives necessary information regarding requirements to make the booking (for example, it could be instructions like “No patients under 18, pre-authorisation must be provided for insured patients, referral letter for GP required“)
    • • The patient instructions as returned within the schedule.contained[].HealthcareService(ResourceType).extraDetails field (for example, “Fast from 10 pm the night before“, or “Please arrive with a full bladder“).
    • • If displaying the estimated price, the user MUST be made aware that this is an estimate and is NOT guaranteed, and will vary depending on insurance status and other factors.

• • To prevent double bookings, reserve the preferred slot by calling the Reserve Slot API. This will return a unique reservation ID, which should be stored until the booking is complete. Whilst the reservation of multiple slots is not prevented, this should only be used in scenarios such as booking a course of weekly treatments rather than holding several slots on the same day.

• • Prompt the user for all additional information if not already known (name, address, date of birth, etc.)
    • • The booking portal should record as much detail as possible, and perform all necessary validations on the patient data as it is entered. (i.e., validate the correct email and telephone number formats, and ensure the address is correct) before being submitted to ICE. Where the API documentation states that certain data values must be obtained from a Healthcode or FHIR reference table, then these must be checked and validated.
    • • Mandatory fields to record on a booking include first and last names, date of birth, gender, address, and their contact telephone number OR email address (ideally both, but only one or the other is mandatory).
    • • Optional fields should be completed whenever possible so that as much information as possible can be passed to the diary owners. This includes the free-text description which can be used to provide additional information to the diary owners, giving them a general idea as to the reason for making the booking; ie,  symptoms or injury if relevant, date of onset, or if any specific treatment or procedure the patient wishes to discuss.  The optional reason code (ICD9) can also be used to provide diagnosis details.
    • • If the user entry process is taking longer than 5 minutes, the reservation will expire.
        • • A reservation can be extended ONCE to give an additional 5 minutes if required (Extend Slot Reservation API).
        • • Once it expires, a new reservation will need to be requested (assuming that the slot is still available).

• • If the user completes the process, prompt the user to proceed with the booking or cancel.
    • • If the user wishes to proceed, create the appointment using the reservation id.
    • • Note, although FHIR allows for various appointment statuses (such as proposed and pending), within the ICE service definition, ALL new appointments should be set to “booked“.
    • • If the booking isn’t completed, cancel the reservation. Note: integrators are required to ensure that unwanted reservations are cancelled as quickly as possible by calling the Cancel Slot Reservation API rather than waiting for the reservation to expire after 5 minutes.

• • The patient id field within the request to Create Appointment API can be any reference number you wish to assign to this patient, either for your own use or one that may help the diary owners match them to their own patient lists.
  • Insurance Companies must populate the following fields when creating the appointment:
    • Insurer (Healthcode’s insurance company code to identify who the patient is insured by)
    • Registration ID (Insurer’s unique membership number / policy number)
    • Authorisation No (Insurer’s authorisation number for this service/treatment, if known)

• • If the booking is in any way related to NHS treatment, then the patient’s NHS number must be recorded in the nhsNumber field. This field can also be used to store CHI number for Scotland, and IHI number for Northern Ireland.
  • You should record one or more “identifiers” which will serve as YOUR unique booking ID for this appointment. The unique booking identifier returned by ICE may change if the booking is rescheduled, so by adding your own, you can track the appointment in the future, even if it is rescheduled.

• • Once the appointment booking is submitted and confirmation returned, store the resulting Appointment ID for future reference.

It is the integrators responsibility to prevent the system from being abused via their booking portal.

For example, allowing a patient/member to book multiple appointments for the same service without a clinical need. (ie, booking 3 appointments with the intention of cancelling 2 of them at a later date)

Booking an appointment using practitioner data from The PPR

If you are not using your own list of practitioners, you can subscribe to The PPR (Private Practice Register) service which allows you to perform searches against a database of 35,000+ practitioners. Searches can be made by applying filters such as specialty, subspecialty, name, insurer recognition, geographic location etc. There is also a filter to only include practitioners who are using the ICE service. See the PPR APIs page for more details.

The following bullets set out the high-level integration workflow from the booking portals using The PPR.

• • Search for practitioners using The PPR’s Search Practitioners API.

• • Additionally, The PPR’s Get Profile Photo API can be used to retrieve photos of the practitioners, which can then be displayed as part of your practitioner selection process. As the images returned from The PPR can be large in size, it is recommended that these are cached as each photo is requested, and then updated periodically.

• • Follow the same steps as the previous section for the rest of the booking workflow, except for supplying one or specific practitioner IDs from The PPR search results retrieved above.

Retrieving the booking status

• • The appointment ID can be used to retrieve the current status of the booking. This can be used to determine if the patient attended the appointment, or if it was cancelled or rescheduled. The diary owner may have added additional details to the comment field, or recorded a cancellation reason code.

Example workflows for PMS and Hospital integration

It is important to remember that practitioners must have a valid PPR record before they can publish their availability into ICE. The PPR record is used to record their name, contact details, specialty, qualifications, and also where they have practising privileges. A practitioner’s PPR record is associated with a unique practitioner ID which is shared across all Healthcode products/services to identify that individual practitioner. Each treatment location also has a unique ID (also shared across Healthcode products/services), and only locations recorded within the given practitioner’s PPR record can be published into ICE. Changes made to The PPR may take a few hours to propagate to ICE.

PMS / Hospital configuration

The supplier should provide clear instructions to enable their users to correctly configure their software for use with ICE. These actions should be self-service and require no action from Healthcode.

• • The PMS software itself does not need a system API key, instead, each practitioner should log into their Healthcode Account (accounts.healthcode.co.uk) and obtain their own API Key. This should then be configured into the correct settings/preferences screen within the PMS and used for all API calls to ICE. Systems containing diaries for multiple practitioners may need to record multiple API keys. The PMS provider should provide adequate instructions for their users to obtain the API key and add it to the relevant configuration page within the PMS.
  • Hospital systems can follow the same process, but their API key will give access to ALL practitioners registered at that location.

• • For Sandbox (UAT) testing, Healthcode can supply the integrators with credentials to test their system, using synthetically generated practitioner records.

• • The practitioner’s Healthcode site ID is also required, as this needs to be included in many of the API calls. This is displayed in the Healthcode Account portal. Refer to the instructions here for details.

• • It is strongly recommended that a test call is made at this stage to validate that the API credentials have been correctly copied.

• • Each location that the user wants to publish their availability for must have its correct Healthcode hospital ID associated with it. These are the same codes used by the Healthcode clearing services and all other products/services, so may already be recorded. Any missing locations should be manually added or automatically synced from their PPR record. PMS systems can use the Search Practitioner Role API to retrieve a list of all valid locations for a given practitioner. If this list is cached locally, there should be the ability to refresh the list in case new locations are added/removed from their PPR record. PMS systems should inform their users that any changes made to their PPR record may take several hours to be updated within ICE.

• • Each service type that will be made available to book (such as initial consultation, follow-up consultation, etc) must have a valid ISC (Industry Standard Code) assigned to it. Again, these are the same service type codes as used by Healthcode clearing services and other products/services and can be looked up from the Reference/Master Data APIs.
  • NOTE: It is NOT necessary to publish ALL of your services to ICE;  You are free to publish as many or as few services as you feel are relevant. For example, you may choose only to publish Initial Consultations, then use your current booking processes for any treatments/follow-up visits.

Offline Considerations

As ICE is a live system, planning consideration should be given to allow for instances when, for whatever reason, the ICE system cannot be contacted (internet outage, expired credentials, planned maintenance, etc). If ICE is not reachable, systems should be designed to fail gracefully. If necessary, some transactions may need to be batched by the PMS and processed once back online. Alternatively, actions should fail gracefully and request that the user tries again at a later time.

Discovery Document / Website URLs

The Discovery Document must be used to get the current URL endpoints for APIs, as these may change without notice.

If the PMS system needs to refer users to Healthcode’s websites, these URLs should also be taken from the Discovery Document rather than being hard-coded.

ice_product_overview_endpoint : Healthcode’s ICE product web page explaining what ICE is and the benefits to users.

ice_ppr_registration_endpoint: Healthcode’s PPR registration page, allowing users to create a free PPR profile.

ice_healthcode_account_endpoint: Healthcode’s account login page, where existing users can log in to update their PPR and manage their ICE subscriptions.

Creating availability (schedules)

Schedules relate to a specific location where the service will be conducted. A practitioner can only publish schedules for locations that they have declared in their PPR profile.  Other locations will be rejected.

It is suggested that the user is only able to select locations from those listed in their PPR record. The user should be shown a link to the PPR site (link available from within the Discovery Document) so that the user can add or update their location list if necessary.

Although ICE supports recurring schedules, it is strongly recommended that occurrences are generated from within the PMS system using their own recurrence logic, with each session of availability (for example, a morning clinic) being published into ICE as a separate schedule. This will remove any discrepancies between how the PMS and ICE handle recurrence.

Each schedule only contains a single service type (initial consultation, follow-up, etc.), so if multiple services are to be made available you should create multiple schedules – one for each service.

Each schedule published to ICE will return a unique schedule ID which should be recorded by the PMS for future reference. This may mean that multiple ICE schedules may need to be recorded against a single PMS schedule if the PMS schedule allows for multiple service types.

Each schedule can record an estimated service price. Although technically optional, the diary owners should be strongly encouraged to specify a price, otherwise the schedule could be overlooked when searches are performed. ie, if a search is performed with filter criteria of services being “less than £100” or “greater than £100”, NEITHER search would find an appointment with NO price specified.

The way in which schedules are filled can be controlled using the option “frontLoading” and “backLoading” extensions.

• If a schedule is set to “frontLoading”, only the FIRST available slot of each schedule will be published, forcing bookings to be made sequentially from the start of the clinic.
• If set to “backLoading”, only the LAST slot of each schedule is published, so the diary is filled from the END time of the clinic backwards. 
• These settings can be combined, so that bookings are made from both ends of the clinic, gradually filling up towards the middle. If neither is specified, all available slots will be published (default).
• When using frontLoading or backLoading it MAY still be possible for a gap to be left in the diary if someone has currently reserved the first/last slot but does not complete the booking. The system will then try to fill that gap when the next appointment is made.
• As “frontLoading” and “backLoading” are applied to schedules, and each schedule represents one service, users could utilise this so that all Initial Consultations are booked at the start of the day and all Follow-Up Consultations at the end.

By default, all schedules are published as being “in-person” appointments, held at a physical location. However, a schedule can use the “allowRemoteAppointment” flag to publish the appointments as also being available as remote (video) consultations. The “allowInPersonAppointment” flag can be set to “false” to prevent face-to-face appointments from being booked.

By default, all schedules have a “bookingNoticeHours” set to 24 hours. This means that appointments cannot be booked less than 24 hours prior to the appointment time. This can be overridden per schedule, from anything from zero hours (allow immediate bookings) to 1500 hours (approx 3 months).

The “communicationLanguages” extension allows you to record one or more languages that the practitioner is able to communicate using. This includes both spoken and non-verbal forms of communication, such as sign languages. Languages are specified using 3-letter ISO 639.3:2007 codes. Multiple language codes can be comma-seperated. If not specified, the communicationLangues defaults to “eng” (English).

Creating a large number of schedules (multiple dates, recurrence, multiple services, etc) may take a short time to process. During this time it is recommended to give your user some form of visual feedback, such as “Processing schedule 1 of xx. Please wait.”

Amending a schedule

• • Schedules can only be amended/deleted if the changes do not affect any existing booking. For example, channel permissions can be updated, as can the start/end time of the sessions providing that no existing bookings are affected.

Keeping PMS diary in sync with the latest details from ICE

This action MUST be performed each time BEFORE the PMS diary is shown to the user. It could also be run on a schedule to reduce the number of changes that need to be processed each time.

• • Check ICE for any changes since last checked. It is recommended that the PMS system stores the date/time of the last synchronisation so that future checks can utilise the List Appointments API using the updatedSince parameter to only return changes since you last checked.

• • Apply any changes to the PMS diary.

• • If required, log changes in the PMS for the user to review/action. This may include processing appointments for patients whose details don’t directly match a patient within the PMS system, sending appointment confirmation letters, etc.
    [Note: It is generally accepted that the diary owners responsible for sending out booking confirmation texts/emails/letters/instructions and not the party who initiated the booking. In most cases this would be the responsibility of the practitioner’s practice management system (PMS)].
  • It is at the discretion of individual integrators how they choose to match new patient appointments to their existing patient database.
    • It is strongly advised to match on multiple fields, such as surname, first initial, DOB, postcode, etc.
    • Also remember that new bookings from insurers should include their membership ID, which can also help with matching.
    • Note that FHIR allow Date Of Birth to be specified in the format YYYY-MM-DD, but also just as YYYY-MM and YYYY. It is at the discretion of the integrating software how such dates are handled. (ie, default DOB to YYYY-MM-01 / YYYY-01-01, etc)

• • The party who made the booking (the distribution channel) can be identified from the appointment details, which may be of use to the diary owners.

• • Provisions must be made to allow for non-mandatory fields in ICE (such as title or insurer) which may be mandatory in the PMS system.

• • Whilst ICE will not allow double booking, there may be scenarios where bookings are made directly into the PMS whilst it is offline, and therefore unable to synchronise with ICE. If the PMS allows its users to make offline bookings, then it must also contain a mechanism to handle double bookings when it does become online. Ideally, the diary user should be warned that the diary may be out of date when unable to communicate with ICE.

If the user is forced to wait for the synchronisation to complete, an appropriate message should be displayed to inform them of the progress. Additionally, a progress bar could be displayed as the total number of appointments to be processed is known from the count value of the Search Appointments API results.

Additional consideration for handling the display of diary within a PMS

• • If the diary is left on-screen for a prolonged period, it is recommended that it is refreshed at regular intervals.

Booking an appointment

• • Ensure the diary is synchronised with the latest details from ICE as per instructions set out in the previous section.

• • Allow the user to select the location/time/date/etc.

• • Immediately place a reservation with ICE, recording the reservation ID issued in the results.

• • If a reservation cannot be made, that slot may have already been taken in the time it took to select the required time slot. In this scenario, the booking process must be aborted, and request the user to select a different slot from a refreshed list.

• • Complete the booking process within the PMS, collecting all necessary patient information.

• • Ideally, show the user a 5-minute countdown to complete the booking.

• • If the user requires more than 5 minutes, request a reservation extension before the current reservation expires. (Note that this is limited to one extension per reservation).

• • Confirm the appointment into ICE using the reservation ID or release the reservation if the booking process is aborted.

• • The appointment must contain a patient ID, which can be the patient’s unique identifier within the PMS system or some other unique reference you wish to assign.

Amending an appointment

• • Whenever an appointment is amended (either with updated details or re-scheduled to a new time/date) it is VITAL that all external appointment identifiers are preserved. By doing this, the party who created the appointment can know of the change. It is not acceptable to cancel an appointment and re-book using a new appointment ID without including external appointment identifiers, as the original booking system will only be informed of the cancellation.

• •  

Rescheduling an appointment

FHIR does not support easily rescheduling a booking once it has been made. Instead, the following process should be followed:

• • Make a record of all “identifier” fields from the existing appointment. These include identifiers added by 3rd parties to allow them to track this booking. (ie, all “identifier” fields except for ICE’s own “booking_identifier” which is unique to each booking)

• • Create a NEW appointment at the required date/time, with the same patient details and comments ensuring that all “identifier” fields from the original appointment are included.

• • Update the “comments” of the original booking to note that the booking has been reschedule. Ideally, include the new date/time in the comment. (note that changes to “comments” should be appended to any existing comments, rather than over-writing them.)

• • Cancel the original appointment by using “Patch Appointment API” to set the appointment-status to “cancelled” and (optional) set a cancellation reason code.

Note, preserving the “identifier” fields allows 3rd parties to track changes to bookings using their own unique identifiers.

Updating appointment status and comments

• • Whenever the status of the appointment changes, the Update Appointment API should be called to reflect the new status. For example:
    • • Patient has arrived : Change the appointment-status to arrived
    • • Patient failed to arrive : Change the appointment-status to noshow
    • • Patient attended and has left : Change the appointment-status to fulfilled

• • Comments can also be updated within the appointment, which can be viewed by the party (distribution channel) that made the booking. Care should be taken to append new comments rather than just overwriting any existing important comments. (Reminder: “Comment” is a “String” type in FHIR, so don’t support text formatting or linebreaks)

Users of the PMS system should be made aware that they have 5 days from the appointment date to correctly set the appointment status, otherwise the appointment will be assumed to have been fulfilled, and the practitioner will be charged for the ICE booking.

Booking meetings and other non-availability within a PMS

• • When recording periods of unavailability (meetings, court cases, holidays, etc.) these should be published immediately into ICE using the Unavailability API. Unavailability overrides any scheduled availability for that time period.

Periodic reconciliation of data between a PMS system and ICE service

In addition to regularly polling ICE for new/amended appointments, it is also recommended that you occasionally compare a wider date range of appointment and schedule information held within your PMS to that stored within ICE and report on the results.

• • Check that all appointments stored in the PMS also exist in the ICE system.

• • Request a list of appointments from the ICE system and ensure that they all exist in the PMS.

• • Similar checks should also be performed periodically to compare published schedules and periods of unavailability.

It is important for PMS integrators to remember that the hospital/clinic where a service will be performed AUTOMATICALLY has shared ownership over that session. They can change the session times, book/amend/cancel appointments, add/edit/delete unavailability, etc.

Offboarding

If a practitioner no longer works for a given location, they should update their profile in The PPR to reflect this change. This will prevent any new schedules from being created for that location, however, any existing schedules will need to be removed by the PMS system. Bear in mind that schedules can not be deleted if they already contain appointments.

Care should also be taken if a practitioner stops using a particular PMS system. Their schedules should be deleted to prevent new bookings from being made, which they then wouldn’t be able to access. Alternatively, create an unavailability entry spanning the time period that their schedules were created up to.

Key Steps to booking an appointment

Search availability

To search availability the calling application must call the Search Slots API by inputting any filters the user has selected. Remember that all dates/times are recorded in UTC time format. The calling application must convert these times into local time when displaying them to the user, taking into account changes for Daylight Saving Time depending on the appointment date. 

Book the appointment

Once the user enters all the required appointment details and submits the form the calling application must call Create Appointment API to create the appointment record within the ICE system.

Appointments booked by Private Medical Insurers (PMIs) must ensure that the appointment correctly contains the insurer code (to identify the insurance company), and the registration ID (patient’s membership number). Use of the authorizationno field to communicate pre-authorisation details is optional but strongly encouraged. Also, any additional information that would be beneficial to the diary owners should be included in the comment field (out-patient limits, what investigations/treatments have been pre-authorised, etc).

It is the responsibility of the diary management system (either the PMS or the Hospital system, whoever has control of the diary) to send any confirmation letters, reminders, emails, SMS, etc to the patient.

If a “remote appointment” has been made, ICE will include two web links in the appointment response. One is for the patient to click on to join the appointment, and the other is for the practitioner.  The patient’s URL should be communicated to the patient as part of any confirmation email/SMS etc.

Create an appointment using a reservation

The Create Appointment API enables submitting an appointment into the ICE platform.

Appointment resources are used to provide information about a planned appointment that may be in the future. The resource only describes a single appointment; a series of repeating visits would require multiple appointment resources to be created for each instance.

To create an appointment, it is recommended that a corresponding slot is reserved first using the Reserve Slot API, which returns a unique reservation ID, and then the reservation ID can be used to create the appointment resource. A reservation expires after 5 minutes, so the appointment needs to be made within 5 minutes of reserving the slot.

Patient resources should be added to the appointment resource in a contained array of the resource.

When a reservation ID is used within an appointment, most of the information needed to create the appointment is already fed into the system when the slot is reserved. So the appointment resource, in this case, can have a minimum set of information and the system will refer to the reserved slot for items such as schedule, start-time, end-time, practitioner, location, service, etc.

Create an appointment without a reservation

An appointment CAN be booked without prior reservation of the slot. In this case, the user needs to provide the schedule reference, start-time and end-time of the slot within the appointment resource.

It is mandatory to use the same schedule reference, start date/time, end date/time and slot identifier as returned in the Search Slots API. The only difference is that a prior reservation of the slot is NOT made in this case. Validations on the slot will be performed to check if the appointment has the same information as the searched slot.

The patient resource should be added to the appointment resource in a contained array of the resource. (See API documentation for examples)

If NOT using a reservation, it is more likely that the slot may have already been taken by someone else during the duration of the integrating system having searched for that slot and subsequently submitting the create-appointment request. In such cases, the Create Appointment API call will return an error status.

Update an appointment

The Update Appointment API enables changes to be submitted to appointments already created in the ICE system.

Only the diary owners can update an appointment. ie, a booking portal is NOT permitted to amend a booking once it has been made.

Only patient demographics, appointment status and comments can be modified or updated.  If the date/time or any other details need to be changed then the appointment should be cancelled and recreated with the correct information.

Cancel an appointment

An appointment can be cancelled by setting it’s “appointment-status” to being “cancelled”. This can be done using the Patch Appointment API.

It is strongly suggested to append the appointment “comment” field with any information that should be fed back to the booking originator. 

Optionally, the “cancellation reason” code can also be set.

Only the diary owners can cancel an appointment. A booking portal (channel) is NOT permitted to cancel a booking. They should instead contact the diary owners to request the cancellation.