NHS England FHIR Implementation Guide (deprecated)

Important Announcement regarding this Implementation Guide
  • As of 04/10/2023, this implementation guide has been deprecated and all development on the legacy NHS England FHIR Implementation Guide assets has ceased.
  • Therefore, vendors looking to start new implementations or looking to update existing implementations should use the new NHS England Implementation Guide. Vendors continuing to implement legacy NHS England FHIR Implementation Guide based solutions do so at their own risk and on the understanding that no maintenance or support will be available.

FHIR Messaging

This is the FHIR version of traditional messaging. It differs from FHIR RESTful in that all the resources are sent to the recipient in one interaction. This is particularly useful between organisations where all the FHIR resources can be sent in one interaction.

The general FHIR principle that resources MUST be self contained still applies. FHIR Messaging should not be used to send highly coupled complex interactions, the message SHOULD be easily converted into resource based interactions. A FHIR Message bundle is not a storage based concept, it should be expected that all the resources in the Bundle can be processed individually. Should this be required consider using FHIR Documents

FHIR Messaging should only be used for defined interactions/messages, ad-hoc interactions/collections should use transactions

E.g. in the diagram below a prescription consists of one Patient resource and two MedicationRequests. Using FHIR Messaging all the resources are sent within one FHIR Message Bundle. Doing the same with FHIR RESTful would require at least three transactions (possibly more depending on the handling of the Patient resource).

rest vrs fhir 1

FHIR Message reduces the number of transactions and decouples the sending organisation from local rules. All the resources are handled in a single package and the receiving organisation can handle them according to local procedures.

FHIR Messaging is very similar to the messaging used in HL7 v2 and HL7 v3 (/ITK), hence the term traditional messaging.

FHIR Bundle (type=message)

Profile url

useΣ ?!0..1codeBinding
systemS Σ1..1uri
valueS Σ1..1string
periodΣ I0..1Period
assignerΣ I0..1Reference(Organization)
typeS Σ1..1codeBindingFixed Value
timestampS Σ1..1instant
totalΣ I0..1unsignedInt
resourceS Σ I0..1NHSDigitalMessageHeader

This message consists of a Bundle identified by the type "message", with the first resource in the bundle being a MessageHeader resource. The MessageHeader resource has a code - the message event - that identifies the nature of the request message, and it also carries additional request metadata. The other resources in the bundle depend on the type of the request.

For example a dispense-notification message will be a FHIR Bundle consisting of

  • one MessageHeader resource with an eventCoding dispense-notification
  • one to four MedicationDispense resources
  • one (optional) Patient resource.

Example dispense-notifications can be found in the NHS Digital Medicines Guide Examples

These Bundles are send to a $process-message operation, e.g.

POST baseUrl/$process-message

In the example above we stated rules for the dispense-notification message, these will be contained in a FHIR MessageDefinition and the message definition for this is https://fhir.nhs.uk/MessageDefinition/dispense-notification

    "resourceType": "MessageDefinition",
    "id": "bf729ea8-280b-4109-b2f5-02ce8e51d870",
    "url": "https://fhir.nhs.uk/MessageDefinition/dispense-notification",
    "identifier":  [
            "system": "https://tools.ietf.org/html/rfc4122",
            "value": "bf729ea8-280b-4109-b2f5-02ce8e51d870"
    "version": "1.0.0",
    "name": "NHSDigitalDispenseNotification",
    "title": "Pharmacy/Treatment Dispense",
    "status": "active",
    "date": "2020-10-02",
    "eventCoding": {
        "system": "https://fhir.nhs.uk/CodeSystem/message-event",
        "code": "dispense-notification",
        "display": "Dispense Notification"
    "description": "Notification of dispensed medication",
    "category": "notification",
    "focus":  [
            "code": "MedicationDispense",
            "profile": "https://fhir.nhs.uk/StructureDefinition/NHSDigital-MedicationDispense-Message",
            "min": 1,
            "max": "*"


Some of the key points are:

  • element eventCoding This is the code that identifies the MessageDefinition and will match the eventingCode in the dispense-notification FHIR Message
  • element focus This lists the principal resources; in the example this is FHIR MedicationDispense resources which follows the NHSDigital-MedicationDispense profile. One and up to four resources can be supplied.
  • Patient resource is not in the focus section. The rule that a Patient resource is required is contained in the FHIR MedicationDispense profile.
  • MessageHeader resource is not in the focus section. It is mandatory in all FHIR Messages.

The FHIR MessageHeader contains the message metadata only and is designed to support message handling without having to process the full message. The use of FHIR MessageHeader with NHSDigital API's is discussed in NHSDigital-MessageHeader. Note this FHIR R4 NHSDigital-MessageHeader is designed to handle all message types and contains rules from both previous MessageHeaders used in Transfer of Care (point to point messages) and National Event Messaging System (pub/sub messages).

back to top