---
title: "Search for healthcare services (A035, FHIR R4)"
method: GET
path: "/R4/HealthcareService"
tags: ["Retrieve healthcare service information"]
---

# Search for healthcare services (A035, FHIR R4)

`GET /R4/HealthcareService`

## Overview

A Patient may have 0 to 20 Services associated with a single referral. 
A service is a place where a referrer can send a patient or obtain clinical advice concerning a specific patient. 
You can use this endpoint to obtain a set of services (up to 20) and their associated attributes, in a single call. 

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

## Pre-requisites
### Application-restricted access
In order to use this endpoint you must be an authenticated e-RS calling application, working in the context of a Referring Organisation.

### Healthcare worker, user-restricted access
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 at least one service ID in order to use this endpoint.

## Use case
As an authenticated user

I would like to obtain information about all services on my patient's current shortlist

So that I can review the entire shortlist of services and each service's current attributes

## Related endpoints
  -  You can retrieve service IDs on a referral via [[HYPERLINK_A005]] as long as the referral has a shortlist of at least one service.
  -  You can check if a cached service has changed via [[HYPERLINK_A037]].
  -  You can fetch the attributes of a single service via [[HYPERLINK_A033]].

## Known Issues
The HealthcareService.type attribute is being returned as a singular object by this endpoint. As per the [FHIR standard](https://hl7.org/fhir/R4/), this attribute should be an array. See our [problems and fixes](https://digital.nhs.uk/services/e-referral-service/api/updates-and-releases/problems-and-fixes) section for more information.

## Sandbox test scenarios
You can test the following scenarios in our sandbox environment

| Scenario                                                                                                      | Service Id |
| ------------------------------------------------------------------------------------------------------------- | ---------- |
| Search for multiple service with minimal attributes                                                           | `1,2`      |
| Search for multiple service max and min attributes                                                            | `3`,`4`    |
| Search for multiple service, where the service IDs are formatted correctly, but none of the service IDs match | `5`,`6`    |

## Query parameters

- `_id` string, required

## Parameters

- `#/paths/~1R4~1Practitioner/get/parameters/0` — unresolved $ref
- `#/paths/~1R4~1Binary~1%7Bid%7D/get/parameters/3` — unresolved $ref
- `#/paths/~1R4~1Binary~1%7Bid%7D/get/parameters/2` — unresolved $ref
- `#/paths/~1R4~1Practitioner/get/parameters/1` — unresolved $ref

## Response `200`

Bundle resource containing the `eRS-HealthcareService` resources associated to the supplied search criteria. 
The canonical URL: https://fhir.hl7.org.uk/StructureDefinition/UKCore-Bundle

## Other responses

- `400` — Where status code 400 (Bad Request) is returned then an [NHSDigital-OperationOutcome](https://fhir.nhs.uk/StructureDefinition/NHSDigital-OperationOutcome) will be included in the body, as detailed below. Check diagnostics property for specific information regarding the error. | issue.details.coding.code | issue.code | Coding System | Description | | ------------------------- | ---------- | ----------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------| | REC_BAD_REQUEST | invalid | [BaRS Error Code](https://fhir.nhs.uk/CodeSystem/http-error-codes) | Incorrect or missing expected value. For example; Service Id is invalid or missing, or an an attempt to request more than 20 Service Ids |
- `401` — unresolved $ref
- `403` — unresolved $ref
- `404` — unresolved $ref
- `406` — unresolved $ref
- `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-service-production.skmtc.workers.dev/v1/apis/nhs/e-referrals-service-api/revisions/916969ea472f/schema)