Retrieve a patient’s structured record

Retrieve a patient's record in structured format

Use case

Retrieve a patient’s record in FHIR® structured format from a GP practice.

Security

GP Connect utilises TLS Mutual Authentication for system level authorization
GP Connect utilises JSON Web Tokens (JWT) to transmit clinical audit and provenance details

Prerequisites

Consumer

The consumer system:

MUST have previously resolved the organisation’s FHIR endpoint base URL through the Spine Directory Service
MUST have previously traced the patient’s NHS Number using the Personal Demographics Service or an equivalent service

API usage

Interaction diagram

Get structured record interaction diagram

Request operation

FHIR® relative request

POST /Patient/$gpc.getstructuredrecord

FHIR® absolute request

POST https://[proxy_server]/https://[provider_server]/[fhir_base]/Patient/$gpc.getstructuredrecord

Request headers

Consumers MUST include the following additional HTTP request headers:

Header	Value
`Ssp-TraceID`	Consumer’s Trace ID (a GUID or UUID)
`Ssp-From`	Consumer’s ASID
`Ssp-To`	Provider’s ASID
`Ssp-InteractionID`	`urn:nhs:names:services:gpconnect:fhir:operation:gpc.getstructuredrecord-1`

Example HTTP request headers:

Accept: application/fhir+json;charset=utf-8
Content-Type: application/fhir+json;charset=utf-8
Ssp-TraceID: 629ea9ba-a077-4d99-b289-7a9b19fd4e03
Ssp-From: 200000000115
Ssp-To: 200000000116
Ssp-InteractionID: urn:nhs:names:services:gpconnect:fhir:operation:gpc.getstructuredrecord-1

Payload request body

The payload request body comprises a Parameters resource, conforming to the GPConnect-GetStructuredRecord-Operation-1 OperationDefinition profile.

The Parameters resource is populated with the parameters shown below. Note: The ↳ character indicates a part parameter.

Name	Type	Optionality	Comments
`patientNHSNumber`	`Identifier`	Mandatory	NHS Number of the patient for whom to retrieve the structured record.
`includeAllergies`		Optional	Include allergies and intolerances in the response.
↳ `includeResolvedAllergies`	`Boolean`	Mandatory	Include resolved allergies and intolerances in the response. Part parameter: may only be provided if `includeAllergies` is set.
`includeMedication`		Optional	Include medication in the response.
↳ `includePrescriptionIssues`	`Boolean`	Mandatory	Include each prescription issue in the response. Part parameter: may only be provided if `includeMedication` is set.
↳ `medicationSearchFromDate`	`Date`	Optional	Restrict medications returned on or after the date specified. Rules: If the `medicationSearchFromDate` is not specified, all medication will be returned. If the `medicationSearchFromDate` is populated, all medications which are active on or after the `medicationSearchFromDate` MUST be returned. `medicationSearchFromDate` MUST be populated with a date less than or equal to the current date. `medicationSearchFromDate` MUST be populated with whole dates only (for example, 01-02-2017) - that is, no partial dates, or with a time period or offset. Part parameter: may only be provided if `includeMedication` is set.

Important: Consumer guidance: it is advised that a single call is made to retrieve all structured data required for a patient. In addition, the parameter filters should be applied to reduce the payload.

The example below shows a fully populated Parameters resource as a request to the $gpc.getstructuredrecord operation:

{
  "resourceType": "Parameters",
  "parameter": [
    {
      "name": "patientNHSNumber",
      "valueIdentifier": {
        "system": "https://fhir.nhs.uk/Id/nhs-number",
        "value": "9999999999"
      }
    },
    {
      "name": "includeAllergies",
      "part": [
        {
          "name": "includeResolvedAllergies",
          "valueBoolean": true
        }
      ]
    },
    {
      "name": "includeMedication",
      "part": [
        {
          "name": "includePrescriptionIssues",
          "valueBoolean": true
        },
        {
          "name": "medicationSearchFromDate",
          "valueDate": "2017-06-04"
        }
      ]
    }
  ]
}

Error handling

The provider system MUST return a GPConnect-OperationOutcome-1 resource that provides additional detail when one or more data field is corrupt or a specific business rule/constraint is breached.

The table below shown common errors that may be encountered during this API call, and the returned Spine error code. Please see Error handling guidance for additional information needed to create the error response, or to determine the response for errors encountered that are not shown below.

Errors returned due to parameter failure MUST include diagnostic information detailing the invalid parameter.

Error encountered	Spine error code returned
The `Parameters` resource passed does not conform to that specified in the GPConnect-GetStructuredRecord-Operation-1 `OperationDefinition`	`INVALID_RESOURCE`
No recognised parameters are provided	`INVALID_PARAMETER`
The `patientNHSNumber` parameter is not provided	`INVALID_PARAMETER`
The `patientNHSNumber` parameter value is invalid, for example it fails format or check digit tests	`INVALID_NHS_NUMBER`
The `medicationSearchFromDate` part parameter contains a partial date, or has a value containing a time or offset component	`INVALID_PARAMETER`
The `medicationSearchFromDate` part parameter is greater than the current date	`INVALID_PARAMETER`
The `includeAllergies` parameter is passed without the corresponding `includeResolvedAllergies` part parameter	`INVALID_PARAMETER`
The `includeMedication` parameter is passed without the corresponding `includePrescriptionIssue` part parameter	`INVALID_PARAMETER`
The patient has dissented to sharing their clinical record	`NO_PATIENT_CONSENT`
A patient could not be found matching the `patientNHSNumber` provided	`PATIENT_NOT_FOUND`
The request is for the record of an inactive or deceased patient	`PATIENT_NOT_FOUND`
The request is for the record of a non-Regular/GMS patient (i.e. the patient’s registered practice is somewhere else)	`PATIENT_NOT_FOUND`
The patient’s NHS number in the provider system is not associated with a NHS number status indicator code of ‘Number present and verified’	`PATIENT_NOT_FOUND`
The request is for a sensitive patient	`PATIENT_NOT_FOUND`

Request response

Response headers

HTTP/1.1 200 OK
Cache-Control: no-store
Content-Type: application/json+fhir; charset=utf-8
Date: Sun, 07 Aug 2016 11:13:05 GMT
Content-Length: 1464

Payload response body

Provider systems MUST:

return a 200 OK HTTP status code to indicate successful retrieval of a patient’s structured record
return a Bundle conforming to the GPConnect-StructuredRecord-Bundle-1 profile definition
return the following resources in the Bundle:
- Patient matching the NHS Number sent in the body of the request
- Organization matching the patient’s registered GP practice, referenced from Patient.generalPractitioner
- Organization matching the organisation serving the request, if different from above, referenced from Patient.managingOrganization
- Practitioner matching the patient’s usual GP, if they have one, referenced from Patient.generalPractitioner
- PractitionerRole matching the usual GP’s role
- resources holding allergies, intolerance, medication information and warnings according to the rules below:

Provider systems SHOULD:

provide a consistent order to elements within the Bundle resource. It is recommended to follow the order described in the Bundle population illustrated diagram.

Consumers systems MUST NOT:

rely on order or index of elements within the Bundle resource in order to parse encapsulated resources.

Allergies

Provider systems MUST include the following in the response Bundle:

when the includeAllergies parameter is not set:
- no allergy or intolerance information shall be returned
when the includeAllergies parameter is set:
- and when the includeResolvedAllergies parameter is set to false:
  - List and AllergyIntolerance resources representing the patient’s allergies and intolerances, excluding those marked as resolved or ended
- and when the includeResolvedAllergies parameter is set to true:
  - List and AllergyIntolerance resources representing the patient’s allergies and intolerances, including those marked as resolved or ended
Organization, Practitioner and PractitionerRole resources that are referenced by the AllergyIntolerance resources

Medications

Provider systems MUST include the following in the response Bundle:

when the includeMedication parameter is not set:
- no medication information shall be returned
when the includeMedication parameter is set:
- List, MedicationStatement, MedicationRequest with an intent of plan and Medication resources representing the patient’s medication summary information (authorisations and medication prescribed elsewhere)
- when the medicationSearchFromDate parameter is set:
  - all medications which are active on or after the medicationSearchFromDate MUST be returned
    - A medication is considered active between its effective.start and effective.end (inclusive)
      - when a medication does not have an effective.end:
        
        an acute medication is considered active on its effective.start only
        
        a repeat medication is considered on-going and is active from its effective.start
        
        when a medication is not defined as an acute or repeat it MUST be treated as repeat
- and when the includePrescriptionIssues parameter is set to false:
  - no prescription issue information should be returned
- and when the includePrescriptionIssues parameter is set to true:
  - MedicationRequest resources with an intent of order representing the patient’s prescription issues, for the above medication summary data
Organization, Practitioner and PractitionerRole resources that are referenced by the MedicationStatement and MedicationRequest resources

Medication search date

The medicationSearchFromDate identifies the start date of the requested medications search period. An end date cannot be requested by a consumer, so that all searches go to the end of the patient’s record.

The scenarios below represent how a selection of acute and repeat medications are returned based on the search date in the request. Each scenario has a different search date. Medications that have been greyed out are not returned in the response.

Search date: 15/01/2018 Current date: 08/10/2018

Search date: 01/03/2018 Current date: 08/10/2018

Search date: 08/07/2018 Current date: 08/10/2018

Search date: 08/10/2018 Current date: 08/10/2018

Bundle population illustrated

The following diagram illustrates the population of the response Bundle according to the parameters in the inbound Parameters request resource:

Structured Bundle response

Payload response examples

Examples of the payload requests and responses can be found here:

Tags:

API Hub

Explore and Make use of Nationally Defined Messaging APIs

Retrieve a patient's structured record