Migrating from the send for triage endpoints to the book/defer endpoint

Learn how to make changes to your integrated software in order to use the mixed shortlist functionality.

Overview

This page explains how to migrate your integrated e-Referral Service (e-RS) application from using the 'send for triage' endpoints to using the book/defer endpoint.

This change introduces the concept of a mixed shortlist, which allows a Referral Assessment Service (RAS) to be added to a referral shortlist.

Mixed shortlist functionality:

improves patient choice, inline with the NHS Choice Framework
simplifies the way an integrated system sends a referral to a service

Who will be affected

All partners integrated with the following API endpoints:

What we are doing

These two API endpoints were deprecated in March 2024.

According to our sunsetting policy, they will be withdrawn from service in March 2025. At this point, the API endpoints will no longer be available for use.

API partners should migrate their functionality to make use of:

Create referral (A011) and Book or defer appointment (A016) in place of Create referral and send for triage (A021),
Change shortlist (A031) and Book or defer appointment (A016) in place of Change shortlist and send for triage (A032)

Why we are making the change

As part of the NHS Choice Framework, the e-RS has made changes to give patients greater choice and control over how they receive their healthcare. This new functionality is called mixed shortlists.

Prior to the support of mixed shortlists, it was possible for a professional user to either:

Shortlist one or more bookable services.
Send a referral to a single triage service.

Option 1 gave the patient a choice on the service they would like to attend. Whereas option 2 removed that choice at the point of referral.

It is now possible for a user to shortlist one or more bookable and/or triage services. This provides choice to the patient regardless of the service type the providing organisation chose to use.

Now that bookable and triage services can be shortlisted in the same way there is no need for the specific triage endpoints.

Next steps

Review referrer use cases
Make endpoint changes

1. Review referrer use cases

The guidance for referrer use cases has been updated to incorporate mixed shortlist functionality.

Review the updated guidance for each use case:

2. Make endpoint changes

It is now possible to simplify your integrated solution.

Referrals can be sent to a specific service in the same way regardless of service type.

This means that sending a referral to a triage service is always done as a separate step from the initial referral creation, or after re-shortlisting.

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.

2.1 Create referral and send for triage

If your integrated application uses Create referral and send for triage (A021), then the same behaviour can be achieved by calling:

Create referral (A011) to create the referral.
Book or defer appointment (A016) to send the referral to a triage service on the shortlist.

The worked example shows old (A021) and new (A011 and A016) behaviour.

It is still possible to shortlist a single triage service, as the example shows. However, where possible, referrers should promote patient choice.

This means shortlisting multiple services for a patient.

Worked example

Using A021

Create a referral, shortlist a single triage service and send the referral to that triage service.

POST /STU3/ReferralRequest/$ers.createReferralAndSendForTriage

{
  "resourceType": "Parameters",
  "meta": {
    "profile": [
      "https://fhir.nhs.uk/STU3/StructureDefinition/eRS-CreateReferralAndSendForTriage-Parameters-1"
    ]
  },
  "parameter": [...]
}

HTTP 201 (Created)

{
    "id": "000000070000",
    "meta": {
        "versionId": "3",
        "profile": [
            "https://fhir.nhs.uk/STU3/StructureDefinition/eRS-ReferralRequest-1"
        ]
    },
    "resourceType": "ReferralRequest",
    "extension": [
        ...
        {
            "url": "https://fhir.nhs.uk/STU3/StructureDefinition/Extension-eRS-ReferralState-1",
            "extension": [
                {
                    "url": "state",
                    "valueCoding": {
                        "system": "https://fhir.nhs.uk/STU3/CodeSystem/eRS-ReferralState-1",
                        "code": "AWAITING_TRIAGE",
                        "display": "Awaiting Triage"
                    }
                },
                {
                    "url": "reason",
                    "valueCoding": {
                        "system": "https://fhir.nhs.uk/STU3/CodeSystem/eRS-ReviewReason-1",
                        "code": "TRIAGE"
                    }
                }
            ]
        },
        ...
    ],
    ...
}

At this point the referral has been created and sent to the shortlisted triage service.

Using A011 and A016

1. Create a referral and shortlist a single triage service

POST /STU3/ReferralRequest/$ers.createReferral

{
  "resourceType": "Parameters",
  "meta": {
    "profile": [
      "https://fhir.nhs.uk/STU3/StructureDefinition/eRS-CreateReferral-Parameters-1"
    ]
  },
  "parameter": [...]
}

HTTP 201 (Created)

{
    "id": "000000070000",
    "meta": {
        "versionId": "3",
        "profile": [
            "https://fhir.nhs.uk/STU3/StructureDefinition/eRS-ReferralRequest-1"
        ]
    },
    "resourceType": "ReferralRequest",
    ...
    "extension": [
        ...
        {
            "url": "https://fhir.nhs.uk/STU3/StructureDefinition/Extension-eRS-ReferralState-1",
            "extension": [
                {
                    "url": "state",
                    "valueCoding": {
                        "system": "https://fhir.nhs.uk/STU3/CodeSystem/eRS-ReferralState-1",
                        "code": "NOT_BOOKED",
                        "display": "Not Booked"
                    }
                }
            ]
        },
        ...
    ],
    ...
}

At this point the referral has been created and the triage service shortlisted, but the referral has not been sent to a service.

Choice

A patient can use the online portal (Manage Your Referral) to send the referral to the triage service, or any other service on their shortlist.

A professional can use the professional web application or through the API to send the referral to the triage service, or any other service on the shortlist.

2. Send the referral to a shortlisted triage service

POST /STU3/Appointment

{
    "id": "appointment",
    "meta": {
        "profile": [
            "https://fhir.nhs.uk/STU3/StructureDefinition/eRS-Appointment-1",
            "https://fhir.hl7.org.uk/STU3/StructureDefinition/CareConnect-Appointment-1"
        ]
    },
    "language": "en",
    "resourceType": "Appointment",
    "status": "proposed",
    "reason": [
        {
            "coding": [
                {
                    "system": "https://fhir.nhs.uk/STU3/CodeSystem/eRS-ReviewReason-1",
                    "code": "TRIAGE"
                }
            ]
        }
    ],
    "description": "e-Referral Appointment",
    "incomingReferral": [
        {
            "reference": "ReferralRequest/000000070000/_history/3"
        }
    ],
    "participant": [
        {
            "actor": {
                "identifier": {
                    "system": "http://fhir.nhs.net/Id/ers-service",
                    "value": "11004"
                }
            },
            "status": "accepted"
        },
        {
            "actor": {
                "identifier": {
                    "system": "http://fhir.nhs.net/Id/nhs-number",
                    "value": "9912003888"
                }
            },
            "status": "accepted"
        }
    ]
}

HTTP 201 (Created)

{
    "id": "70000",
    "meta": {
        "versionId": "1",
        "profile": [
            "https://fhir.nhs.uk/STU3/StructureDefinition/eRS-Appointment-1",
            "https://fhir.hl7.org.uk/STU3/StructureDefinition/CareConnect-Appointment-1"
        ]
    },
    "language": "en",
    "resourceType": "Appointment",
    "status": "proposed",
    ...
    "reason": [
        {
            "coding": [
                {
                    "system": "https://fhir.nhs.uk/STU3/CodeSystem/eRS-ReviewReason-1",
                    "code": "TRIAGE"
                }
            ]
        }
    ],
     ...
     "incomingReferral": [
        {
            "reference": "ReferralRequest/000000070000/_history/4"
        }
    ],
    ...
}

At this point the referral has now been sent to the shortlisted triage service.

The ReferralRequest state will be updated to AWAITING_TRIAGE when the appointment is created. To see the latest version of the referral use Retrieve referral request (A005).

2.2 Change shortlist and send for triage

If your integrated application uses Change shortlist and send for triage (A032), then the same behaviour can be achieved by calling:

Change shortlist (A031) to change the shortlist.
Book or defer appointment (A016) to send the referral to a triage service on the shortlist.

The worked example shows old (A032) and new (A031 and A016) behaviour.

It is still possible to shortlist a single triage service, as the example shows. However, where possible, referrers should promote patient choice.

This means shortlisting multiple services for a patient.

Worked example

Using A032

Change the shortlist on an existing referral and send the referral to a triage service.

POST /STU3/ReferralRequest/000000070000/$ers.changeShortlistAndSendForTriage

{
    "resourceType": "Parameters",
    "meta": {
        "profile": [
            "https://fhir.nhs.uk/STU3/StructureDefinition/eRS-ChangeShortlistAndSendForTriage-Request-Parameters-1"
        ]
    },
    "parameter": [...]
}

HTTP 200 (OK)

{
    "meta": {
        "profile": [
            "https://fhir.nhs.uk/STU3/StructureDefinition/eRS-ChangeShortlistAndSendForTriage-Response-Parameters-1"
        ]
    },
    "resourceType": "Parameters",
    "parameter": [
        {
            "name": "updatedReferralRequest",
            "resource": {
                "id": "000000070000",
                "meta": {
                    "versionId": "3",
                    "profile": [
                        "https://fhir.nhs.uk/STU3/StructureDefinition/eRS-ReferralRequest-1"
                    ]
                },
                "resourceType": "ReferralRequest",
                "extension": [
                    ...
                    {
                        "url": "https://fhir.nhs.uk/STU3/StructureDefinition/Extension-eRS-ReferralState-1",
                        "extension": [
                            {
                                "url": "state",
                                "valueCoding": {
                                    "system": "https://fhir.nhs.uk/STU3/CodeSystem/eRS-ReferralState-1",
                                    "code": "AWAITING_TRIAGE",
                                    "display": "Awaiting Triage"
                                }
                            },
                            {
                                "url": "reason",
                                "valueCoding": {
                                    "system": "https://fhir.nhs.uk/STU3/CodeSystem/eRS-ReviewReason-1",
                                    "code": "TRIAGE"
                                }
                            }
                        ]
                    }
                ],
                ...
            }
        },
        {
            "name": "createdAppointment",
            "resource": {
                "id": "70001",
                "meta": {
                    "versionId": "1",
                    "profile": [
                        "https://fhir.nhs.uk/STU3/StructureDefinition/eRS-Appointment-1",
                        "https://fhir.hl7.org.uk/STU3/StructureDefinition/CareConnect-Appointment-1"
                    ]
                },
                "language": "en",
                "resourceType": "Appointment",
                "status": "proposed",
                ...
                "reason": [
                    {
                        "coding": [
                            {
                                "system": "https://fhir.nhs.uk/STU3/CodeSystem/eRS-ReviewReason-1",
                                "code": "TRIAGE"
                            }
                        ]
                    }
                ],
                ...
            }
        }
    ]
}

At this point the shortlist has been updated and the referral has been sent to a triage service.

Using A031 and A016

1. Change the shortlist on an existing referral and shortlist a single triage service.

POST /STU3/ReferralRequest/000000070000/$ers.changeShortlist

{
    "resourceType": "Parameters",
    "meta": {
        "profile": [
            "https://fhir.nhs.uk/STU3/StructureDefinition/eRS-ChangeShortlist-Parameters-1"
        ]
    },
    "parameter": [...]
}

HTTP 200 (OK)

{
    "id": "000000070000",
    "meta": {
        "versionId": "3",
        "profile": [
            "https://fhir.nhs.uk/STU3/StructureDefinition/eRS-ReferralRequest-1"
        ]
    },
    "resourceType": "ReferralRequest",
    "extension": [
        ...
        {
            "url": "https://fhir.nhs.uk/STU3/StructureDefinition/Extension-eRS-ReferralState-1",
            "extension": [
                {
                    "url": "state",
                    "valueCoding": {
                        "system": "https://fhir.nhs.uk/STU3/CodeSystem/eRS-ReferralState-1",
                        "code": "NOT_BOOKED",
                        "display": "Not Booked"
                    }
                }
            ]
        },
        ...
    ],
    ...
}

At this point the referral has been created and the triage service shortlisted, but the referral has not been sent to a service.

Choice

A patient can use the online portal (Manage Your Referral) to send the referral to the triage service, or any other service on their shortlist.

A professional can use the professional web application or through the API to send the referral to the triage service, or any other service on the shortlist.

2. Send the referral to a shortlisted triage service

POST /STU3/Appointment

{
    "id": "appointment",
    "meta": {
        "profile": [
            "https://fhir.nhs.uk/STU3/StructureDefinition/eRS-Appointment-1",
            "https://fhir.hl7.org.uk/STU3/StructureDefinition/CareConnect-Appointment-1"
        ]
    },
    "language": "en",
    "resourceType": "Appointment",
    "status": "proposed",
    "reason": [
        {
            "coding": [
                {
                    "system": "https://fhir.nhs.uk/STU3/CodeSystem/eRS-ReviewReason-1",
                    "code": "TRIAGE"
                }
            ]
        }
    ],
    "description": "e-Referral Appointment",
    "incomingReferral": [
        {
            "reference": "ReferralRequest/000000070000/_history/3"
        }
    ],
    "participant": [
        {
            "actor": {
                "identifier": {
                    "system": "http://fhir.nhs.net/Id/ers-service",
                    "value": "11004"
                }
            },
            "status": "accepted"
        },
        {
            "actor": {
                "identifier": {
                    "system": "http://fhir.nhs.net/Id/nhs-number",
                    "value": "9912003888"
                }
            },
            "status": "accepted"
        }
    ]
}

HTTP 201 (Created)

{
    "id": "70000",
    "meta": {
        "versionId": "1",
        "profile": [
            "https://fhir.nhs.uk/STU3/StructureDefinition/eRS-Appointment-1",
            "https://fhir.hl7.org.uk/STU3/StructureDefinition/CareConnect-Appointment-1"
        ]
    },
    "language": "en",
    "resourceType": "Appointment",
    "status": "proposed",
    "reason": [
        {
            "coding": [
                {
                    "system": "https://fhir.nhs.uk/STU3/CodeSystem/eRS-ReviewReason-1",
                    "code": "TRIAGE"
                }
            ]
        }
    ],
    ...
     "incomingReferral": [
        {
            "reference": "ReferralRequest/000000070000/_history/4"
        }
    ],
    ...
}

At this point the referral has now been sent to the shortlisted triage service.

The ReferralRequest state will be updated to AWAITING_TRIAGE when the appointment is created. To see the latest version of the referral use Retrieve referral request (A005).

Last edited: 19 July 2024 11:38 am