---
title: "Patient service search (A010, FHIR STU3)"
method: POST
path: "/STU3/HealthcareService/$ers.searchHealthcareServicesForPatient"
tags: ["Refer patient", "Request advice"]
---

# Patient service search (A010, FHIR STU3)

`POST /STU3/HealthcareService/$ers.searchHealthcareServicesForPatient`

## Request

- Base URL: `https://sandbox.api.service.nhs.uk/referrals/FHIR`
- URL: `https://sandbox.api.service.nhs.uk/referrals/FHIR/STU3/HealthcareService/$ers.searchHealthcareServicesForPatient`
- Auth: HTTP bearer

## Overview
Use this endpoint to find services that meet the referral needs of a patient.

## Supported security patterns
- Healthcare worker, user-restricted access

## Pre-requisites
In order to use this endpoint you must be an authenticated e-RS user and use one of the following e-RS roles:
  - `REFERRING_CLINICIAN`
  - `REFERRING_CLINICIAN_ADMIN`

You need to have identified a `patient`, for example via [[HYPERLINK_PDS]].

## Use case
As an authenticated user

I need to find services I can refer the patient to

So that I can offer the patient appropriate services that meet their referral needs

## Important Notes
If using this endpoint for modifying an existing Referral (such as via the [[HYPERLINK_A031]] endpoint for example), you will need to provide the Commissioning Rule Organisation parameter. This ensures that the services returned in the response are valid for use with the Referral. You can obtain the 'Commissioning Rule Organisation' from [[HYPERLINK_A005]].

## Related endpoints
Once you have identified appropriate services for the patient you can create a referral by choosing a shortlist of bookable and/or triage services using [[HYPERLINK_A011]]. You may then subsequently be able to use [[HYPERLINK_A016]] to book an appointment to a directly bookable service if an appointment slot is available, defer the booking responsibility to a directly bookable service if no appointment slot is available, or refer a patient into a triage service.

## Parameters

- `#/paths/~1STU3~1Task/get/parameters/0` (unresolved $ref)
- `#/paths/~1STU3~1Task/get/parameters/1` (unresolved $ref)
- `#/paths/~1STU3~1Slot/get/parameters/2` (unresolved $ref)
- `#/paths/~1STU3~1Task/get/parameters/4` (unresolved $ref)

## Request body

- object: The parameters used in patient services search
  - `meta` object, required
    - `profile` string[], required
  - `resourceType` 'Parameters', required
  - `parameter` union[], required: | Field | Cardinality | Notes | | ------------------------------- | ----------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `RequestType` | `1..1` | | | `SortBy` | `1..1` | | | `Patient` | `1..1` | | | `SearchCriteria` | `1..1` | | | `ReferringClinician` | `0..1` | | | `CommissioningRuleOrganisation` | `0..1` | Required if searching for services for an existing Referral. This field should be provided using the returned Commissioning Rule Organisation already included on the Referral to ensure the services returned are valid. Note this field is not supported when searching with the `ADVICE_AND_GUIDANCE_REQUEST` request type. |
    - union
      - object: The type of request in e-RS which this service search is aimed at creating or updating. The options are appointment request (i.e. referral) or advice and guidance request. Services may support one or the other or both and will be filtered accordingly.
        - `name` 'requestType', required
        - `valueCoding` object, required
          - `system` 'https://fhir.nhs.uk/STU3/CodeSystem/eRS-RequestType-1', required
          - `code` 'APPOINTMENT_REQUEST' | 'ADVICE_AND_GUIDANCE_REQUEST', required
      - object: The service search returns the top results according to the sorting requested. Therefore, the sorting requested affects the selection of services that are included in the response.
        - `name` 'sortBy', required
        - `valueCoding` object, required
          - `system` 'https://fhir.nhs.uk/STU3/CodeSystem/eRS-SortBy-1', required
          - `code` 'DISTANCE' | 'IWT', required
          - `display` string
      - 0 (unresolved $ref)
      - 1 (unresolved $ref)
      - object: Parameter to supply a commissioning rule organisation
        - `name` 'commissioningRuleOrganisation', required
        - `valueIdentifier` object, required
          - `system` 'https://fhir.nhs.uk/Id/ods-organization-code', required
          - `value` string, required
      - object
        - `name` 'searchCriteria', required
        - `resource` object, required: The criteria used to search for services
          - `id` string, required
          - `meta` object, required
            - `profile` string[], required
          - `resourceType` 'Parameters', required
          - `parameter` union[], required: | Field | Cardinality | Notes | | --------------------------------------- | ----------- | ------------------------------------------------------------------------------------------- | | `Priority` | `1..1` | | | `Specialty` | `0..1` | | | `ClinicType` | `0..1` | | | `IndicativeAppointmentWaitTimeLimit` | `0..1` | | | `Postcode` | `0..1` | | | `DistanceLimit` | `0..1` | | | `ClinicalTerm` | `0..1` | | | `NamedClinician` | `0..1` | | | `AgeAndGenderAppropriate` | `1..1` | Details the age and sex appropriate flag used in a search criteria. Content in the e-RS Professional Application has changed to replace 'Gender' with 'Sex'. This represents the data better and uses inclusive language. | | `CommissioningProvisioning` | `0..1` | This filter parameter is no longer supported as an input. If provided it will be ignored and a value of `ALL_AVAILABLE_FOR_BOOKING` used. Stored historical values will continue to be returned for output. | | `Organisation` | `0..1` | This parameter is not included in the response when retrieving the service search criteria. | | `Place` | `0..1` | Only supported in read mode, search by `place` is not possible currently. |
            - union
              - …

## Response `200`

The response body contains the list of services (if any) that match the search criteria provided

- object: Service search response
  - `meta` object, required
    - `profile` string[], required
  - `resourceType` 'List', required
  - `status` 'current', required
  - `mode` 'snapshot', required
  - `emptyReason` object
    - `coding` object[], required
      - `system` 'http://hl7.org/fhir/ValueSet/list-empty-reason', required
      - `code` 'nilknown' | 'notasked' | 'withheld' | 'unavailable' | 'notstarted' | 'closed', required
      - `display` string, required
  - `entry` object[], required
    - `extension` object[], required
      - `extension` union[], required: | Field | Cardinality | Notes | | --------------------------------- | ----------- | ------------------------------------------ | | `DisplayProminently` | `1..1` | | | `Distance` | `0..1` | | | `IndicativeAppointmentWaitTime` | `1..1` | |
        - union
          - object: Extension to supply display prominently indicator
            - `url` 'displayProminently', required
            - `valueBoolean` boolean, required
          - object: Extension to supply distance value
            - `url` 'distance', required
            - `valueUnsignedInt` integer, required
          - object: Extension to supply indicative wait time, only one extension with url value 'indicativeAppointmentWaitTime' will be returned at once
            - `url` 'indicativeAppointmentWaitTime', required
            - `valueUnsignedInt` integer, required
          - object: Extension to supply indicative wait time, only one extension with url value 'indicativeAppointmentWaitTime' will be returned at once
            - `url` 'indicativeAppointmentWaitTime', required
            - `valueCodeableConcept` object, required
              - …
      - `url` 'https://fhir.nhs.uk/STU3/StructureDefinition/Extension-eRS-ServiceSearch-ListItem-1', required
    - `item` object, required
      - `extension` object[], required
        - `url` 'https://fhir.nhs.uk/STU3/StructureDefinition/Extension-eRS-ServiceSummaryView-1', required
        - `extension` union[], required: | Field | Cardinality | Notes | | -------------------------------- | ----------- | ------------------------------------------ | | `SupportedAppointmentType` | `0..1` | | | `ServiceName` | `1..1` | | | `SupportedRequestFlowType` | `1..2` | | | `IndicativeTreatmentWaitTime` | `0..1` | | | `BookableType` | `1..1` | | | `Location` | `1..1` | | | `ReferrerAlert` | `0..1` | | | `Exclusions` | `0..1` | | | `SuggestedInvestigations` | `0..1` | | | `ConditionsTreated` | `0..1` | | | `GenderTreated` | `1..1` | Sex treated. Content in the e-RS Professional Application has changed to replace 'Gender' with 'Sex'. This represents the data better and uses inclusive language. | | `AdditionalRequirementSupported` | `0..3` | | | `ReferralLetterRequired` | `1..1` | | | `Specialty` | `1..1` | |
          - union
            - object: Supported appointment type
              - …
            - object: Name of the service.
              - …
            - object: Services can support one or two Request Flow Types, but not Triage Request and Appointment Request simultaneously.
              - …
            - object: Statistical indication of how long Patients have waited before receiving treatment.
              - …
            - object: Statistical indication of how long Patients have waited before receiving treatment.
              - …
            - object: Whether the service is Directly or Indirectly Bookable
              - …
            - object: Link to NHS website providing information about the Service such as contact details, map, department, facilities and reviews.
              - …
            - object: Service location
              - …
            - object: Referrer Alert
              - …
            - object
              - …
            - object: Suggested investigations
              - …
            - object: Conditions treated
              - …
            - object: Age range treated
              - …
            - object: Sex treated
              - …
            - object: Additional support services provided by the Organisation where the Service is located at
              - …
            - object: Indicates whether the Service requires a referral letter before they consider a referral to be valid
              - …
            - object: The specialty supported by the Service
              - …
      - `identifier` Identifier, required (unresolved $ref)

## Other responses

- `400` (unresolved $ref)
- `401` (unresolved $ref)
- `403` (unresolved $ref)
- `406` (unresolved $ref)
- `415` (unresolved $ref)
- `422`: Where status code 422 (Unprocessable Entity) is returned then an eRS-OperationOutcome-1 will be included in the body, as detailed below. Check diagnostics property for specific information regarding the error. | Error code | Description | | ---------------------------------- | ----------------------------------------------------------------------------------------------------------------------- | | REFERENCE_NOT_FOUND | A supplied reference could not be resolved to valid resource (e.g. a patient, clinician or an organisation). | | INAPPROPRIATE_VALUE | A value, which is acceptable under different conditions, is inappropriate in the context of the other information provided. | | MISSING_VALUE | A field defined as mandatory for an endpoint has not been provided. | | VALUE_IS_REQUIRED | A business rule defines a value as mandatory but it has not been provided. | | FIELD_NOT_PERMITTED | A business rule defines a field as not permitted but it has been provided. | | PATIENT_ERROR | An error occurred while retrieving the requested patient. Do not attempt again. | | INVALID_VALUE | The input provided does not conform to the expected data types and format. | | INVALID_CODE | The input provided for a field is not one of the defined legal values. | | UNEXPECTED_FIELD | A field is provided that is not expected as part of the request. E.g. a field is mis-spelt, was defined on a previous version of the endpoint but has subsequently been removed. | | INVALID_FHIR_STRUCTURE | The FHIR data structure in the message body does not match the expected structure (e.g. an array is present for a value when no array is expected). | | REFERENCED_USER_IS_NOT_SPC | The user provided does not have the Service Provider Clinician authorisation in the e-RS. | | ORGANISATION_IS_CLOSED | The organisation supplied corresponds to an organisation that is closed. | | ORGANISATION_NOT_APPROPRIATE | The organisation supplied corresponds to an organisation that is not valid for the given request. | | REFERENCED_USER_IS_NOT_ACTIVE | The user identified is not active. | | REFERENCED_USER_NOT_IN_ORG | The referenced user does not belong to organisation specified. | | NO_REG_GP_PRACTICE | The patient provided was found not to have a registered GP practice in the e-RS. | | REFERENCED_USER_IS_NOT_RC | The user provided does not have the Referring Clinician authorisation in the e-RS. | | REFERENCED_USER_IS_NOT_RC_AT_ORG | The user provided does not have the Referring Clinician authorisation at the organisation specified. | | SNOMED_NOT_FOUND | A SNOMED code, while potentially valid in the latest version of the international dictionary, is not found in the e-RS dictionary. |
- `429` (unresolved $ref)
- `500` (unresolved $ref)
- `503` (unresolved $ref)

---

[API](https://skmtc.dev/nhs/apis/e-referrals-service-api.md) - [All operations](https://skmtc.dev/nhs/apis/e-referrals-service-api/llms.txt) - [OpenAPI document](https://skmtc.dev/nhs/apis/e-referrals-service-api/revisions/916969ea472f?raw)
