--- title: "Retrieve referral requests for a patient" method: GET path: "/FHIR/R4/ServiceRequest" --- # Retrieve referral requests for a patient `GET /FHIR/R4/ServiceRequest` ## Request - Base URL: `https://int.api.service.nhs.uk/e-referrals-service-patient-care-api` - URL: `https://int.api.service.nhs.uk/e-referrals-service-patient-care-api/FHIR/R4/ServiceRequest` - Auth: HTTP bearer ## Overview Use this endpoint to retrieve active e-RS referrals for an authenticated patient, including summary details relating to its current state. Where the referral is currently being managed by a service provider, this endpoint will reference the Service ID for that service. This can then be used to retrieve the service information using [[HYPERLINK_A002]]. The referrals that are returned by this endpoint are the same referrals that are accessible to the patient via [[HYPERLINK_MANAGE_REFERRAL]]. ## Pre-requisites In order to use this endpoint the patient must be an authenticated user. The patient needs to have authenticated via [[HYPERLINK_NHS_LOGIN]] and meet the required [[HYPERLINK_PROOFING_LEVEL]] (currently this is "P9"). ## Use case As an authenticated user I want to retrieve my referrals So that I can view and manage my referrals ## Related endpoints You can retrieve the attributes of a single service via [[HYPERLINK_A002]] using the Service ID ## Query parameters - `patient:identifier` string, required - `category` '3457005' | 'http://snomed.info/sct|3457005', required - `_revinclude` string[] ## Headers - `X-Correlation-ID` string ## Response `200` The Response contains a FHIR 'Bundle' that, in turn, contains 'ServiceRequest' resources where each 'ServiceRequest' resource can include the latest 'Task' or 'Appointment' associated to the 'ServiceRequest'. - object - `id` string, required - `meta` object, required - `profile` string[], required - `lastUpdated` string, date-time, required - `resourceType` 'Bundle', required - `timestamp` string, date-time, required - `type` 'searchset', required - `total` integer, required - `link` object[], required - `relation` 'self', required - `url` string, required - `entry` union[]: | Field | Cardinality | Notes | | ---------------------- | ----------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `ServiceRequest` | `0..*` | A ServiceRequest might have an Appointment or a Task related, but not both at the same time. If the ServiceRequest is unbooked then it will not have an Appointment or a Task.| | `Appointment` | `0..*` | If the ServiceRequest is booked then it will have one Appointment. Note that multiple Appointments can be returned, but each one will refer to a single ServiceRequest. | | `Task` | `0..*` | If the ServiceRequest has a deferral or a triage deferral. Note that multiple Tasks can be returned, but each one will refer to a single ServiceRequest. | - union - object: The details of an active ServiceRequest. - `fullUrl` string, required - `resource` object, required - `id` string, required - `meta` object, required - `versionId` string, required - `profile` string[], required - `resourceType` 'ServiceRequest', required - `identifier` object[], required - `system` 'https://fhir.nhs.uk/Id/UBRN', required - `value` string, required - `extension` union[], required: | Field | Cardinality | Notes | | ------------------------------------------ | ----------- | --------------------------------------------------------------------- | | `Extension-Portal-Link` | `1..1` | Deep Link into the specific landing page in MYR | | `Extension-ServiceRequest-Priority` | `1..1` | Code for the priority of the referral set by the Referring Clinician | | `Extension-ServiceRequest-State` | `1..1` | Code for the ServiceRequest state | - union - … - `contained` object[]: | Field | Cardinality | Notes | | --------------------------------------- | ----------- | ------------------------------------------ | | `PractitionerRole` | `1..1` | | - `resourceType` 'PractitionerRole', required - `id` string, required - `practitioner` object, required - … - `organization` object, required - … - `meta` object, required - … - `status` 'active', required: The status of the ServiceRequest. - `priority` 'routine' | 'urgent' | 'asap', required - `intent` 'order', required - `category` object[], required - `coding` object[], required - … - `subject` object, required - `identifier` Identifier, required (unresolved $ref) - `requester` object, required - `reference` string, required - `performerType` object: Specialty used to search for the shortlisted service(s) (if one was used). - `coding` Items[], required (unresolved $ref) - `authoredOn` string, date-time, required: Date the referral was initiated in e-RS - `search` object, required - `mode` 'match', required - object: The current Appointment for a ServiceRequest. - `fullUrl` string, required - `resource` object, required - `id` string, required - `resourceType` 'Appointment', required - `meta` object, required - `versionId` string, required - `profile` string[], required - `status` 'booked', required - `basedOn` object[], required - `reference` string, required - `start` string, date-time: Date time of the current appointment booking. - `end` string, date-time: The appointment end date time. - `slot` object[]: When the Healthcare Service is directly bookable then there will be 1 slot, however when it's indirectly bookable then there are no slots. - `identifier` object, required - … - `participant` union[], required: | Field | Cardinality | Notes | | --------------------------------------- | ----------- | ------------------------------------------ | | `HealthcareService` | `1..1` | | | `Patient` | `1..1` | | - union - … - `search` object, required - `mode` 'include', required - object: The current Task for a ServiceRequest. - `fullUrl` string, required - `resource` object, required - `id` string, required - `resourceType` 'Task', required - `status` 'requested', required - `intent` 'order', required - `code` object, required: Indicates what type of task this is. Will differentiate between an appointment deferral and a triage deferral. - `coding` object[], required - … - `focus` object, required: Which ServiceRequest this Deferral is related to. - `reference` string, required - `for` object, required - `identifier` object, required - … - `owner` object, required - `identifier` 0, required (unresolved $ref) - `restriction` object: Review Due Date. If deferred to provider (because there were no appointments available for a directly bookable service) then this is the date by which the provider should resolve the appointment slot issue; or If the ServiceRequest was sent to a triage service then this is the date by which the provider should have reviewed the ServiceRequest. - `period` object, required - … - `meta` object, required - `versionId` string, required - `profile` string[], required - `search` object, required - `mode` 'include', required ## Other responses - `400`: Where status code 400 (Bad Request) is returned then an OperationOutcome will be included in the body, as detailed below. Check diagnostics property for specific information regarding the error. | Error code | Description | | ---------------------------------- | ---------------------------------------------------------------------------------------------------------------------------- | | REC_BAD_REQUEST | The request is invalid, a required parameter is missing. | - `401`: Status code 401 (Unauthorized) is returned when there is a failure on the authentication process. An OperationOutcome will be included in the body, as detailed below. | Error code | Description | | ---------------------------------- | ---------------------------------------------------------------------------------------------------------------------------- | | ACCESS_DENIED | Failure in the authentication process. | - `403`: Where status code 403 (Forbidden) is returned then an OperationOutcome will be included in the body, as detailed below. | Error code | Description | | ---------------------------------- | ---------------------------------------------------------------------------------------------------------------------------- | | REC_FORBIDDEN | The user cannot retrieve the requested data. | - `429`: Status code 429 (Too Many Requests) is returned when too many requests are received in a given amount of time. An OperationOutcome will be included in the body, as detailed below. | Error code | Description | | ---------------------------------- | ---------------------------------------------------------------------------------------------------------------------------- | | TOO_MANY_REQUESTS | Too many requests received. | - `500`: When status code 500 (Internal Server Error) is returned then an OperationOutcome will be included in the body, as detailed below. | Error code | Description | | ---------------------------------- | ---------------------------------------------------------------------------------------------------------------------------- | | REC_SERVER_ERROR | There was an error in the server. | - `504`: Where status code 504 (Gateway Timeout) is returned then an OperationOutcome will be included in the body. An OperationOutcome will be included in the body, as detailed below. | Error code | Description | | ---------------------------------- | ---------------------------------------------------------------------------------------------------------------------------- | | GATEWAY_TIMEOUT | The API operation took too long. | --- [API](https://skmtc.dev/nhs/apis/e-referrals-service-patient-care-api.md) - [All operations](https://skmtc.dev/nhs/apis/e-referrals-service-patient-care-api/llms.txt) - [OpenAPI document](https://skmtc.dev/nhs/apis/e-referrals-service-patient-care-api/revisions/10aae95b47cd?raw)