--- title: "Get patients referrals, bookings, documents, questionnaires and waiting lists" method: GET path: "/aggregator/events" tags: ["Patient Care Aggregator"] --- # Get patients referrals, bookings, documents, questionnaires and waiting lists `GET /aggregator/events` ## Request - Base URL: `https://sandbox.api.service.nhs.uk/patient-care-aggregator-api` - URL: `https://sandbox.api.service.nhs.uk/patient-care-aggregator-api/aggregator/events` - Auth: HTTP bearer The Wayfinder Patient Care Aggregator CarePlan response will return a FHIR [Bundle](https://www.hl7.org/fhir/r4/bundle.html) resource which will contain one [CarePlan](https://www.hl7.org/fhir/r4/careplan.html) resource per Waiting List Entry, one [CarePlan](https://www.hl7.org/fhir/r4/careplan.html) resource containing all Referrals, Appointments, Documents and Questionnaires and one optional [OperationOutcome](https://www.hl7.org/fhir/r4/OperationOutcome.html) resource (based on the UK Core FHIR specification) for use by the NHS App to the following specification. ## Query parameters - `patient:identifier` string, required ## Headers - `X-Correlation-ID` string, uuid, required - `NHSD-ID-Token` string, byte, required ## Response `2XX` The request was valid and the API was able to request information from the various upstream applications. There are two possible outcomes: | HTTP status | Description | | ----------- | ------------------------------------------------------------------- | | 200 | A successful request will return a HTTP status code of `200 OK` containing a FHIR `Bundle` with `0..*` `CarePlan` resources. All upstream systems responded normally. | | 207 | If an error occurs with an upstream service the aggregator will return a `207 Multi-status` containing a FHIR `Bundle` with `0..*` `CarePlan` resources and one `OperationOutcome` with each of the errors listed as issues. | - Bundle: A FHIR `Bundle` resource containing the search results of the request. - `resourceType` 'Bundle', required: FHIR resource type. - `id` string: The X-Correlation-ID from the Request header - `meta` object: Metadata about the resource - `versionId` string: FHIR id string representing the version of the resource - `profile` string[]: Profiles this resource claims to conform to - `type` 'searchset', required: The type of FHIR bundle. - `total` number: The total number of matches - `entry` union[]: The FHIR resources within the bundle. Includes `0..*` `CarePlan` resources (containing referral, booking, document and questionnaire information, if any found) and `0..1` `OperationOutcome` resources (if any upstream system errors occurred). - union - object: Details of the referrals and bookings found for the patient, expressed as a FHIR `CarePlan` resource. - `fullUrl` string, required: URI for the `CarePlan` resource. - `search` object, required: Search-related information for the `CarePlan` resource. - `mode` 'match', required: Indicates why this resource is in the result set - in this case because it includes infomation that matched the requested patient. - `resource` CarePlan, required: A FHIR `CarePlan` resource _describes the intention of how one or more clinicians intend to deliver care for a particular patient for a period of time, for a specific condition_. This represents a pathway of care and contains a summary of Referrals, Appointments, Documents and Questionnaires. - `resourceType` 'CarePlan', required: FHIR resource type. - `meta` object: Metadata about the resource - `lastUpdated` string: The census date for when the pathway of care waiting list was last submitted by the responsible provider i.e. last confirmed as correct. This is mandatory for Waiting List (CarePlans). - `profile` string[]: Profiles this resource claims to conform to - `identifier` object[]: Identifier for the pathway of care - `system` 'https://fhir.nhs.uk/Id/care-pathway-id': Type of identifier. - `value` string: The pathway of care identifier itself. - `status` 'active' | 'completed', required: Status of the care plan. - `intent` 'order', required: Level of authority / intentionality associated with the care plan and where the care plan fits into the workflow chain. - `title` string: Specialty referred to for the pathway of care. - `subject` object, required: Patient or group whose intended care is described by the plan. - `identifier` object, required: Unique identifier for the patient - specifically, their NHS number. - … - `period` object: Time period the pathway of care covers - `start` string: The start date of the pathway of care, typically the referral recevied date. - `end` string: The end date of the pathway of care, typically the treatment or discharged date. - `extension` union[]: FHIR extension wrapper for MPC wait time data. - … - `author` object: The organisation responsible for the pathway of care. This is mandatory for Waiting List (CarePlans). - `type` 'Organization': Type of entity. - `identifier` object - … - `display` string: ODS Organisation name (NHS Trust) - `activity` union[]: Array of referral, appointments, documents and questionnaires related to the patients care. - union - … - object: Details of any errors returnd by upstream applications, expressed as a FHIR `OperationOutcome` resource. - `fullUrl` string, required: URI for the `OperationOutcome` resource. - `search` object, required: Search-related information for the `OperationOutcome` resource. - `mode` 'include', required: Indicates why this resource is in the result set. - `resource` OperationOutcome, required: A FHIR `OperationOutcome` resource containing details of the issues that have occurred. - `resourceType` 'OperationOutcome', required: FHIR resource type. - `id` string: The X-Correlation-ID from the Request header - `meta` object: Metadata about the resource - `profile` string[]: Profiles this resource claims to conform to - `issue` object[], required: An array of issues that occurred in processing the request. Usually there is only one issue, but there can be more than one. - `severity` 'fatal' | 'error' | 'warning' | 'information', required: Severity of the issue. - `code` 'timeout' | 'structure' | 'transient' | 'exception' | 'business-rule', required: Error code for the issue. See [http://hl7.org/fhir/issue-type](http://hl7.org/fhir/issue-type) `timeout` means the request to the upstream application timed out; `structure` means the response received from the upstream application failed validation; `transient` or `exception` means we received an unexpected error from the upstream application; `business-rule` means the response has qualified business logic to suppress or transform the data returned. - `extension` object[]: FHIR `Extension` for the details of which upstream application the `Issue` it relates. - … - `diagnostics` string: Detailed diagnostic information for the issue. ## Other responses - `4XX`: When the aggregator service is unable to serve a successful response a FHIR `OperationOutcome` resource is returned with the relevant HTTP status code defined as follows: | HTTP status | Error code | Description | | ----------- | ------------------- | ------------------------------------------------------------------- | | 400 | `exception` | Missing or invalid NHS number in request | | 401 | `processing` | Missing or invalid OAuth 2.0 bearer token in request | | 401 | `processing` | NHS number in request doesn't match NHS number in NHS login account | | 403 | `forbidden` | Patient is under 16 years of age | | 404 | `not-found` | Invalid value in `NHSD-Target-Identifier` header | | 429 | `TOO_MANY_REQUESTS` | You have exceeded your application's [rate limit](https://digital.nhs.uk/developer/guides-and-documentation/reference-guide#rate-limits). | For details see the `diagnostics` field. - `5XX`: A 5xx status code means the server has a problem. For more details on the most common 5xx status codes and their meanings see the [HTTP status codes](https://digital.nhs.uk/developer/guides-and-documentation/reference-guide#http-status-codes). ## Changes - **2026-06-22** `7aed1189c92d`: 1 info - removed the `VIRTUAL` enum value from the `entry/items/anyOf[subschema #1]/resource/activity/items/anyOf[#/components/schemas/Appointment]/detail/extension/items/anyOf[subschema #4]/valueCode` response property for the response status `2XX` - **2026-06-12** `816cad9e7503`: 2 warning - added the new `TELEPHONE` enum value to the `entry/items/anyOf[subschema #1]/resource/activity/items/anyOf[#/components/schemas/Appointment]/detail/extension/items/anyOf[subschema #4]/valueCode` response property for the response status `2XX` - added the new `VIDEO_CONSULTATION` enum value to the `entry/items/anyOf[subschema #1]/resource/activity/items/anyOf[#/components/schemas/Appointment]/detail/extension/items/anyOf[subschema #4]/valueCode` response property for the response status `2XX` - **2025-10-28** `4075bce0f334`: 1 warning, 1 info - added the new `https://fhir.nhs.uk/CodeSystem/Specialty-1` enum value to the `entry/items/anyOf[subschema #1]/resource/activity/items/anyOf[#/components/schemas/Referral]/detail/extension/items/anyOf[subschema #4]/valueCoding/system` response property for the response status `2XX` - removed the `https://fhir.nhs.uk/STU3/CodeSystem/Specialty-1` enum value from the `entry/items/anyOf[subschema #1]/resource/activity/items/anyOf[#/components/schemas/Referral]/detail/extension/items/anyOf[subschema #4]/valueCoding/system` response property for the response status `2XX` - …earlier changes not shown [Operation history](https://skmtc.dev/nhs/apis/wayfinder-patient-care-aggregator-api/changes/aggregator/events/get.md) --- [API](https://skmtc.dev/nhs/apis/wayfinder-patient-care-aggregator-api.md) - [All operations](https://skmtc.dev/nhs/apis/wayfinder-patient-care-aggregator-api/llms.txt) - [OpenAPI document](https://skmtc.dev/nhs/apis/wayfinder-patient-care-aggregator-api/revisions/4ab46c93472a?raw)