Skip to main content

Migrating from FHIR DSTU2 to FHIR STU3

Learn how to migrate your integrated software to the FHIR Standard for Trial Use (STU) 3

Page contents

Overview

This page explains how to migrate your integrated e-Referral Service (e-RS) application from FHIR DSTU2 (Draft Standard for Trial Use 2) to STU3 (Standard for Trial Use 3).

The e-RS API is built using FHIR standards. These standards and the best practices for integration across the NHS are constantly evolving.

As a result, our DSTU2 endpoints have been superseded. The new endpoints are built on the more stable and widely adopted standard - STU3.

Who will be affected

All partners integrated with the FHIR DSTU2 API endpoints, using HSCN and CIS1 authentication.

The endpoints include:

A004 - Retrieve Reference Data (DSTU2)

A005 - Retrieve Referral (DSTU2)

A006 - Retrieve Attachment (DSTU2)

A007 - Retrieve Clinical Information (DSTU2)

A008 - Retrieve Worklist (DSTU2)

What we are doing

The FHIR DSTU2 API endpoints were deprecated in August 2023. These API endpoints will be withdrawn from the service in August 2024.

At this point, these endpoints will no longer be available for use.

Why we are making the change

The e-RS API uses a global standard for health care data exchange - FHIR.

The standard and best integration practices are constantly evolving. The e-RS must adapt and respond to changes. This ensures that the service continues to deliver reliable, secure and cost-effective products.

The FHIR STU3 endpoints provide enhanced functionality, including application-restricted access and an OpenAPI specification.

Next steps

What you need to do
  • Follow the APIM/CIS2 migration guide
  • Update base paths
  • Make endpoint changes

1. Follow the APIM/CIS2 migration guide

Alongside migrating from FHIR DSTU2 to STU3, you must also migrate your application from the HSCN to the e-RS internet-facing API, accessible via the API Management (APIM) platform.

Find out more about migrating from HSCN/CIS1.

2. Update base paths

The base path now includes the FHIR version when accessing the FHIR STU3 endpoints over the internet. It will not include the endpoint version.

HSCN/DSTU2 APIM/STU3
Pattern <Base URL>/v1/<Endpoint Path> <Base URL>/FHIR/STU3/<Endpoint Path>
Example https://api.int1.ers.ncrs.nhs.uk/ers-api/v1/ReferralRequest/000048420911 https://int.api.service.nhs.uk/referrals/FHIR/ STU3/ReferralRequest/000048420911

3. Make endpoint changes

The following section describes changes required to move from DSTU2 to STU3.

This guide aims to highlight the types of changes required, it does not represent an exhaustive list of differences.

Please ensure you review the documentation for each endpoint in detail.

Endpoint HSCN/DSTU2 APIM/STU3
Retrieve reference data (A004) GET <Base URL>/v1/ValueSet/<ValueSet ID> GET <Base URL>/FHIR/STU3/CodeSystem/<CodeSystem ID>
Retrieve referral request (A005) GET <Base URL>/v1/ReferralRequest/<UBRN> GET <Base URL>/FHIR/STU3/ReferralRequest/<UBRN>
Retrieve attachment (A006) GET <Base URL>/v1/Binary/<Binary ID> GET <Base URL>/FHIR/STU3/Binary/<Binary ID>
Retrieve clinical information (A007)  GET <Base URL>/v1/Binary/$ers.generateCRI?UBRN=<UBRN> POST <Base URL>/FHIR/STU3/ReferralRequest/ <UBRN>/$ers.generateCRI
Retrieve referral worklist (A008) POST <Base URL>/v1/ReferralRequest/$ers.fetchworklist POST <Base URL>/FHIR/STU3/ReferralRequest/$ers.fetchworklist

Retrieve reference data (A004)

In FHIR STU3, reference data is now modelled using a CodeSystem rather than a ValueSet.

The same Specialty reference data is available to you, just in a different FHIR format.

The table outlines how key information is modelled:

Field HSCN/DSTU2 APIM/STU3
Documentation A004 - Retrieve Reference Data (DSTU2)

Retrieve reference data (A004, FHIR STU3)
Specialty Endpoint URL GET <Base URL>/v1/ValueSet/SPECIALTY GET <Base URL>/FHIR/STU3/CodeSystem/SPECIALTY
Reference Data Code ValueSet.codeSystem.concept.code: "ALLERGY" CodeSystem.concept.code: "ALLERGY"
Reference Data Display ValueSet.codeSystem.concept.display: "Allergy" CodeSystem.concept.display: "Allergy"
Effective From Date

ValueSet.codeSystem.concept.extension:

{
    "url": "http://fhir.nhs.uk/StructureDefinition/extension-ers-effectivefromdate-1",
    "valueDateTime": "2024-01-01T12:00:00.000Z"
}

CodeSystem.concept.property:

{
    "code": "effectiveFrom",
    "valueDateTime": "2004-06-01T00:00:00.000Z"
}
Effective To Date

ValueSet.codeSystem.concept.extension:

{
    "url": "http://fhir.nhs.uk/StructureDefinition/extension-ers-effectivetodate-1",
    "valueDateTime": "2024-12-01T12:00:00.000Z"
}

CodeSystem.concept.property:

{
    "code": "effectiveTo",
    "valueDateTime": "2004-12-01T00:00:00.000Z"
}

Other reference data is also available in FHIR STU3, see the documentation for details.

Retrieve referral request (A005)

The tables outlines how key information is modelled for this endpoint:

ReferralRequest resource

Field HSCN/DSTU2 APIM/STU3
Documentation A005 - Retrieve Referral (DSTU2)

Retrieve referral request (A005, FHIR STU3)
Endpoint URL GET <Base URL>/v1/ReferralRequest/<UBRN> GET <Base URL>/FHIR/STU3/ReferralRequest/<UBRN>
UBRN ReferralRequest.id ReferralRequest.id
Version ID ReferralRequest.meta.versionId ReferralRequest.meta.versionId
Specialty

ReferralRequest.specialty

"specialty": {
  "coding": [
    {
      "system": "http://fhir.nhs.uk/ValueSet/ers-specialty-1",
      "code": "2WW"
    }
  ]
},

ReferralRequest.specialty

"specialty": {
  "coding": [
    {
      "code": "2WW",
      "system": "<Base URL>/FHIR/STU3/CodeSystem/SPECIALTY",
      "display": "2WW"
    }
  ]
},

ⓘ The Base URL within the system will vary depending on the environment.
Priority

ReferralRequest.priority:

"coding": [
  {
    "system": "http://fhir.nhs.uk/ValueSet/ers-priority-1",
    "code": "ROUTINE"
  }
]

ReferralRequest.extension:

{
  "url": "https://fhir.nhs.uk/STU3/StructureDefinition/Extension-eRS-ReferralPriority-1",
  "valueCodeableConcept": {
    "coding": [
      {
        "code": "ROUTINE",
        "system": "https://fhir.nhs.uk/STU3/CodeSystem/eRS-Priority-1",
        "display": "Routine"
      }
    ]
  }
}
Patient

ReferralRequest.patient.reference: #Patient-1000000001

ⓘ The contained resource referenced must found in ReferralRequest.contained and then the NHS Number taken from the identifier.

ReferralRequest.subject:

"identifier": {
  "system": "http://fhir.nhs.net/Id/nhs-number",
  "value": "1000000001"
}

ⓘ The NHS Number can be extracted directly from the identifier within the subject.
Attachments

ReferralRequest.supportingInformation: #DocumentReference-70001

ⓘ See DocumentReference section for further information.

ReferralRequest.supportingInfo: #DocumentReference-70001
Related Requests

ReferralRequest.supportingInformation

ReferralRequest.supportingInfo
Appointment

ReferralRequest.extension:

{
  "url": "http://fhir.nhs.uk/StructureDefinition/extension-ers-appointment-1",
  "valueReference": {
    "reference": "#appointment"
  }
}

ⓘ See Appointment section for further information.

ReferralRequest.extension:

{
  "url": "https://fhir.nhs.uk/STU3/StructureDefinition/Extension-eRS-Appointment-1",
  "valueReference": {
    "reference": "#appointment"
  }
}
Clinical Information First Submitted

ReferralRequest.extension:

{
  "url": "http://fhir.nhs.uk/StructureDefinition/extension-ers-clinicalinfofirstsubmitted-1",
  "valueDateTime": "2024-02-28T15:45:00.111Z"
}

ReferralRequest.extension:

{
  "url": "https://fhir.nhs.uk/STU3/StructureDefinition/Extension-eRS-ClinicalInfoFirstSubmitted-1",
  "valueDateTime": "2024-02-28T15:45:00.111Z"
}
Clinical Information Last Updated

ReferralRequest.extension:

{
  "url": "http://fhir.nhs.uk/StructureDefinition/extension-ers-clinicalinfolastupdated-1",
  "valueDateTime": "2024-02-29T15:45:00.111Z"
}

ReferralRequest.extension:

{
  "url": "https://fhir.nhs.uk/STU3/StructureDefinition/Extension-eRS-ClinicalInfoLastUpdatedSubmitted-1",
  "valueDateTime": "2024-02-29T15:45:00.111Z"
}

Appointment resource

Field HSCN/DSTU2 APIM/STU3
Start Date/Time Appointment.start Appointment.start
End Date/Time Appointment.end Appointment.end
Service

Appointment.participant.actor:

{
  "actor": {
    "reference": "#HealthcareService-11000",
  },
  "status": "accepted"
}

ⓘ The contained resource referenced must found in ReferralRequest.contained and then the Service ID taken from the identifier.

Appointment.participant.actor:

{
  "actor": {
    "identifier": {
      "system": "http://fhir.nhs.net/Id/ers-service",
      "value": "11000"
    },
  },
  "status": "accepted"
}

ⓘ The Service ID can be extracted directly from the identifier within the actor.
Named Clinician

Appointment.participant.actor:

{
  "type": {
    "coding": [
      {
        "system": "http://hl7.org/fhir/ValueSet/encounter-participant-type",
        "code": "CON"
      }
    ]
  },
  "actor": {
    "reference": "#Practitioner-921600556514"
  },
  "status": "accepted"
}

ⓘ The contained resource referenced must found in ReferralRequest.contained and then the Named Clinician SDS ID taken from the identifier.

Appointment.participant.actor:

{
  "type": {
    "coding": [
      {
        "code": "CON",
        "system": "http://hl7.org/fhir/ValueSet/encounter-participant-type"
      }
    ]
  },
  "actor": {
    "identifier": {
      "system": "http://fhir.nhs.net/Id/sds-user-id",
      "value": "921600556514"
    }
  },
  "status": "accepted"
}

ⓘ The Named Clinician SDS ID can be extracted directly from the identifier within the actor.
NHS Number Not present on the Appointment but can be sourced from ReferralRequest.patient.

Appointment.participant.actor:

{
  "actor": {
    "identifier": {
      "system": "http://fhir.nhs.net/Id/nhs-number",
      "value": "1000000001"
    }
  },
  "status": "accepted"
}

DocumentReference resource

Field HSCN/DSTU2 APIM/STU3
Attachment Type DocumentReference.type DocumentReference.type
Attachment Description DocumentReference.description DocumentReference.description
Attachment Details

DocumentReference.content.attachment:

{
  "id": "70001",
  "extension": [
    {
      "url": "http://fhir.nhs.uk/StructureDefinition/extension-ers-attachedby-1",
      "valueReference": {
        "reference": "#Practitioner-021600556514"
      }
    }
  ],
  "contentType": "text/plain",
  "url": "Binary/att-70000-70001",
  "size": 26,
  "title": "TestFile.txt",
  "creation": "2024-01-01"
}

ⓘ The contained Practitioner resource referenced must found in ReferralRequest.contained and then the Practitioner SDS ID taken from the identifier.

DocumentReference.content.attachment:

{
  "id": "70001",
  "extension": [
    {
      "url": "https://fhir.nhs.uk/STU3/StructureDefinition/Extension-eRS-AttachedBy-1",
      "valueReference": {
        "identifier": {
          "system": "http://fhir.nhs.net/Id/sds-user-id",
          "value": "021600556514"
        }
      }
    }
  ],
  "contentType": "text/plain",
  "url": "Binary/att-70000-70001",
  "size": 26,
  "title": "TestFile.txt",
  "creation": "2024-01-01"
}

ⓘ The Practitioner SDS ID can be extracted directly from the identifier within the valueReference.

Retrieve attachment (A006)

The table outlines how key information is modelled for this endpoint:

Field HSCN/DSTU2 APIM/STU3
Documentation A006 - Retrieve Attachment (DSTU2) Retrieve attachment (A006, FHIR STU3)
Endpoint URL GET <Base URL>/v1/Binary/<Binary ID> GET <Base URL>/FHIR/STU3/Binary/<Binary ID>
File Name Header FILE_NAME: test1.txt Content-Disposition: attachment; filename="test1.txt"

Retrieve clinical information (A007)

The table outlines how key information is modelled for this endpoint:

Field HSCN/DSTU2 APIM/STU3
Documentation A007 - Retrieve Clinical Information (DSTU2)

Retrieve clinical information (A007, FHIR STU3)
Endpoint Method GET POST
Endpoint URL <Base URL>/v1/Binary/$ers.generateCRI?UBRN=<UBRN> <Base URL>/FHIR/STU3/ReferralRequest/ <UBRN>/$ers.generateCRI

Retrieve referral worklist (A008)

The table outlines how key information is modelled for this endpoint:

Field HSCN/DSTU2 APIM/STU3
Documentation A008 - Retrieve Worklist (DSTU2)

Retrieve referral worklist (A008, FHIR STU3)
Endpoint URL POST <Base URL>/v1/ReferralRequest/$ers.fetchworklist POST <Base URL>/FHIR/STU3/ReferralRequest/ $ers.fetchworklist
Item Reference

List.entry.item: ReferralRequest/000048420911

 List.entry.item: ReferralRequest/000048420911
Entry Patient

List.entry.extension[extension-ers-referralsforreview-worklistitem-1].extension:

{
  "url": "patient",
  "valueReference": {
    "reference": "#Patient-1000000001"
  }
}

List.entry.extension[Extension-eRS-ReferralsforReview-WorkListItem-1].extension:

{
  "url": "patient",
  "valueReference": {
    "reference": "#Patient-1000000001"
  }
}
Entry Priority

List.entry.extension[extension-ers-referralsforreview-worklistitem-1].extension:

{
  "url": "priority",
  "valueCodeableConcept": {
    "coding": [
      {
        "system": "http://fhir.nhs.uk/ValueSet/ers-priority-1",
        "code": "URGENT"
      }
    ]
  }
}

List.entry.extension[Extension-eRS-ReferralsforReview-WorkListItem-1].extension:

{
  "url": "priority",
  "valueCodeableConcept": {
    "coding": [
      {
        "system": "https://fhir.nhs.uk/STU3/CodeSystem/eRS-Priority-1",
        "code": "URGENT"
      }
    ]
  }
}
Entry Appointment Start

List.entry.extension[extension-ers-referralsforreview-worklistitem-1].extension:

{
  "url": "appointmentStart",
  "valueDateTime": "2024-01-28T09:00:00.000Z"
}

List.entry.extension[Extension-eRS-ReferralsforReview-WorkListItem-1].extension:

{
  "url": "appointmentStart",
  "valueDateTime": "2024-01-28T09:00:00.000Z"
}
Entry Clinical Information First Submitted

List.entry.extension[extension-ers-referralsforreview-worklistitem-1].extension:

{
  "url": "clinicalInfoFirstSubmitted",
  "valueDateTime": "2024-02-28T15:45:00.111Z"
}

List.entry.extension[Extension-eRS-ReferralsforReview-WorkListItem-1].extension:

{
  "url": "clinicalInfoFirstSubmitted",
  "valueDateTime": "2024-02-28T15:45:00.111Z"
}
Entry Clinical Information Last Updated

List.entry.extension[extension-ers-referralsforreview-worklistitem-1].extension:

{
  "url": "clinicalInfoLastUpdated,
  "valueDateTime": "2024-02-29T15:45:00.111Z"
}

List.entry.extension[Extension-eRS-ReferralsforReview-WorkListItem-1].extension:

{
  "url": "clinicalInfoLastUpdated,
  "valueDateTime": "2024-02-29T15:45:00.111Z"
}
Entry Clinical Information Printed

List.entry.extension[extension-ers-referralsforreview-worklistitem-1].extension:

{
  "url": "clinicalInfoPrinted",
  "valueBoolean": false
}

List.entry.extension[Extension-eRS-ReferralsforReview-WorkListItem-1].extension:

{
  "url": "clinicalInfoPrinted",
  "valueBoolean": false
}
Entry Allocated Clinician

List.entry.extension[extension-ers-referralsforreview-worklistitem-1].extension:

{
  "url": "allocatedClinician",
  "valueReference": {
    "reference": "#Practitioner-021600556514"
  }
}

List.entry.extension[Extension-eRS-ReferralsforReview-WorkListItem-1].extension:

{
  "url": "allocatedClinician",
  "valueReference": {
      "reference": "#Practitioner-021600556514"
  }
}
Entry Request Context Status

List.entry.extension[extension-ers-referralsforreview-worklistitem-1].extension:

{
  "url": "requestContextStatus",
  "valueCodeableConcept": {
    "coding": [
      {
        "system": "http://fhir.nhs.uk/ValueSet/ers-requestcontextstatus-1",
        "code": "NEVER_REVIEWED",
        "display": "Never Reviewed"
      }
    ]
  }
}

List.entry.extension[Extension-eRS-ReferralsforReview-WorkListItem-1].extension:

{
  "url": "requestContextStatus",
  "valueCodeableConcept": {
    "coding": [
      {
        "system": "https://fhir.nhs.uk/STU3/CodeSystem/eRS-RequestContextStatus-1",
        "code": "NEVER_REVIEWED",
        "display": "Never Reviewed"
      }
    ]
  }
}
Entry Specialty

List.entry.extension[extension-ers-referralsforreview-worklistitem-1].extension:

{
  "url": "specialty",
  "valueCodeableConcept": {
    "coding": [
      {
        "system": "http://fhir.nhs.uk/ValueSet/ers-specialty-1",
        "code": "CARDIOLOGY"
      }
    ]
  }
}

List.entry.extension[Extension-eRS-ReferralsforReview-WorkListItem-1].extension:

{
  "url": "specialty",
  "valueCodeableConcept": {
    "coding": [
      {
        "system": "<Base URL>/FHIR/STU3/CodeSystem/SPECIALTY",
        "code": "CARDIOLOGY"
      }
    ]
  }
}

ⓘ The Base URL within the system will vary depending on the environment.
Entry eReferral Pathway Start

List.entry.extension[extension-ers-referralsforreview-worklistitem-1].extension:

{
  "url": "eReferralPathwayStart",
  "valueDateTime": "2024-02-29T15:45:00.111Z"
}

List.entry.extension[Extension-eRS-ReferralsforReview-WorkListItem-1].extension:

{
  "url": "eReferralPathwayStart",
  "valueDateTime": "2024-02-29T15:45:00.111Z"
}
Entry Referral Type

List.entry.extension[extension-ers-referralsforreview-worklistitem-1].extension:

{
  "url": "referralType",
  "valueCodeableConcept": {
    "coding": [
      {
        "system": "http://fhir.nhs.uk/ValueSet/ers-referraltype-1",
        "code": "APPOINTMENT"
      }
    ]
  }
}

List.entry.extension[Extension-eRS-ReferralsforReview-WorkListItem-1].extension:

{
  "url": "referralType",
  "valueCodeableConcept": {
    "coding": [
      {
        "system": "https://fhir.nhs.uk/STU3/CodeSystem/eRS-ReferralType-1",
        "code": "APPOINTMENT"
      }
    ]
  }
}

Last edited: 27 January 2025 12:03 pm