FHIR (Fast Healthcare Interoperability Resouces, pronounced “fire”) is the global standard as set out by HL7.org to facilitate data exchange in the healthcare industry.
Healthcode APIs are built in conformance with HL7 FHIR v4.0.1 (R4) standards. Accordingly, all APIs accept and return data in application/fhir+json format except where explicitly mentioned otherwise. A notable exception is Authentication APIs where the APIs accept and return data in application/json and application/x-www-form-urlencoded formats in accordance with OpenID Connect/OAuth specifications.
Within API requests, the Content-Type header should be set to application/fhir+json. The header is also set within API response to enable the integrating applications to correctly interpret the response content type.
As FHIR was originally an American standard, it continues to use Americanised spellings for resource and parameter names. Also, some of the terminologies may have different or ambiguous meanings in the UK Private Healthcare market, so wherever possible, these differences will be highlighted. Please pay particular attention to words such as specialty (instead of speciality), authorization and organization.
Please note that this document is NOT intended to be an introduction to FHIR, which is a global standard, and overviews can easily be found online including directly from HL7 FHIR http://www.hl7.org/fhir/overview.html
Where FHIR standards are flexible or ambiguous, such as the capitalisation of coding systems, the information in this document takes precedence.
Resource definition conventions
Below are some of the conventions used around API request and response formatting.
- Where bespoke FHIR resources are defined, CamelCase naming is used, consistent with the naming convention used for the standard FHIR resources. Example: Channel, ReserveSlot.
- The resource attribute names use lowerCamelCase naming. For example: Patient.birthDate, Slot.appointmentType.
- The query parameters for Search and List APIs use a hyphen-separated naming. Example: service-category, available-start-time.
- During request and response data structure specification for the APIs, field occurrence values are listed for each parameter in the form of minimum-maximum number of occurrences, where 0-1 indicates that a parameter does not need to be specified (minimum=0) or it can be specified once only (maximum=1). Likewise, an occurrence of 1-* would indicate that the parameter must be specified at least once, with no upper limit on how many times it can occur. 1-1 indicates a mandatory field that has to occur once and only once.
Clinical and Administrative Code Sets
Many of the code sets used by the Healthcode APIs are standard FHIR tables and point directly to the HL7 FHIR site as described here http://hl7.org/fhir/R4/terminologies-valuesets.html. Others use Healthcode’s own reference tables if the data does not exist in the standard FHIR implementation or where UK-specific data takes precedence over the USA data tables. For example, ICE APIs use Healthcode Industry Standard Codes (ISCs) for services/treatments to match the coding system for UK electronic claims, rather than FHIR Snomed/ICD coding systems.
Whenever a value set is listed by both HL7 FHIR and Healthcode, the Healthcode version will always take precedence.
Each API will have links either to the Healthcode References APIs or to the HL7 FHIR site.
Details of Healthcode’s own Reference APIs is available here: Reference/Master Data APIs
Details of the HL7 FHIR value sets can be found here: http://hl7.org/fhir/R4/terminologies-valuesets.html