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	Cardinality	Comments
`patientNHSNumber`	`Identifier`	Mandatory	1..1	NHS Number of the patient for whom to retrieve the structured record.
`includeAllergies`		Optional	0..1	Include allergies and intolerances in the response.
↳ `includeResolvedAllergies`	`Boolean`	Mandatory	1..1	Include resolved allergies and intolerances in the response. Part parameter: may only be provided if `includeAllergies` is set.
`includeMedication`		Optional	0..1	Include medication in the response.
↳ `includePrescriptionIssues`	`Boolean`	Mandatory	1..1	Include each prescription issue in the response. Part parameter: may only be provided if `includeMedication` is set.
↳ `medicationSearchFromDate`	`Date`	Optional	0..1	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.
`includeConsultations`		Optional	0..1	Include consultations in the response.
↳ `consultationSearchPeriod`	`Period`	Optional	0..1	Restrict consultations by defining a time period If the `consultationSearchPeriod` is not specified, all consultations will be returned. If the `consultationSearchPeriod.start` is populated, all consultations on or after the `consultationSearchPeriod.start` MUST be returned. If the `consultationSearchPeriod.end` is populated, all consultations on or before the `consultationSearchPeriod.end` MUST be returned. `consultationSearchPeriod.start` and `consultationSearchPeriod.end` MUST be populated with a date less than or equal to the current date. `consultationSearchPeriod.start` and `consultationSearchPeriod.end` 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 `includeConsultations` is set.
↳ `includeNumberOfMostRecent`	`Integer`	Optional	0..1	Limit the number of returned consultations Part parameter: may only be provided if `includeConsultations` is set.
`includeProblems`		Optional	0..1	Include problems in the response.
↳ `includeStatus`	`Code`	Optional	0..1	Restrict the problems that are returned by their clinical status Part parameter: may only be provided if `includeProblems` is set.
↳ `includeSignificance`	`Code`	Optional	0..1	Restrict the problems that are returned by their clinical significance Part parameter: may only be provided if `includeProblems` is set.
`includeImmunisations`		Optional	0..1	Include immunisations in the response.
`includeUncategorisedData`		Optional	0..1	Include uncategorised data in the response.
↳ `uncategorisedDataSearchPeriod`	`Period`	Optional	0..1	Restrict uncategorised data by defining a time period If the `uncategorisedDataSearchPeriod` is not specified, all uncategorised data will be returned. If the `uncategorisedDataSearchPeriod.start` is populated, all uncategorised data on or after the `uncategorisedDataSearchPeriod.start` MUST be returned. If the `uncategorisedDataSearchPeriod.end` is populated, all uncategorised data on or before the `uncategorisedDataSearchPeriod.end` MUST be returned. `uncategorisedDataSearchPeriod.start` and `uncategorisedDataSearchPeriod.end` MUST be populated with a date less than or equal to the current date. `uncategorisedDataSearchPeriod.start` and `uncategorisedDataSearchPeriod.end` 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 `includeUncategorisedData` is set.

Each clinical area has its own set of search/filter parameters. These parameters will only apply to their own area and MUST have no impact on other parameters.

Important: Consumer guidance: The parameters can be used together in a single call or in multiple calls so that information can be retrieved if is required. It is advised that the number of requests that are made to retrieve a patient’s record are kept to a minimum.

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"
        }
      ]
    },
    {
      "name": "includeConsultations",
      "part": [
        {
          "name": "consultationSearchPeriod",
          "valuePeriod": {
            "start": "2017-12-25",
            "end": "2018-12-25"
          }
        },
        {
          "name": "numberOfMostRecent",
          "valueBoolean": "3"
        }
      ]
    },
    {
      "name": "includeProblems",
      "part": [
        {
          "name": "includeStatus",
          "valueCode": "active"
        },
        {
          "name": "includeSignificance",
          "valueCode": "major"
        }
      ]
    },
    {
      "name": "includeImmunisations"
    },
    {
      "name": "includeUncategorisedData",
      "part": [
        {
          "name": "uncategorisedDataSearchPeriod",
          "valuePeriod": {
            "start": "2016-12-25",
            "end": "2018-12-25"
          }
        }
      ]
    }
  ]
}

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`
The provider could not parse the `Parameters` resource.	`INVALID_RESOURCE`
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 `consultationSearchPeriod` part parameter is greater than the current date	`INVALID_PARAMETER`
The end date of the `consultationSearchPeriod` part parameter is greater than the start date	`INVALID_PARAMETER`
The `consultationSearchPeriod` and `includeNumberOfMostRecent` part parameters are both populated	`INVALID_RESOURCE`
The `uncategorisedDataSearchPeriod` part parameter is greater than the current date	`INVALID_PARAMETER`
The end date of the `uncategorisedDataSearchPeriod` part parameter is greater than the start date	`INVALID_PARAMETER`
The `includeStatus` part parameter contains a value other than `active` or `inactive`	`INVALID_PARAMETER`
The `includeSignificance` part parameter contains a value other than `major` or `minor`	`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`

Forwards and backwards compatibility

Forwards compatibility

Forwards compatibility is the scenario where a consumer requests a higher version of the API than the provider supports. This requires that a provider MUST be able to warn a consumer when they don’t support a requested parameter.

In this scenario, providers MUST respond in the following way:

return a 200 OK HTTP status code to indicate successful retrieval of a patient’s structured record
Include information for supported parameters
as part of the returned bundle, include an OperationOutcome with an issue for each unsupported parameter where:
- code = not-supported
- severity = warn
- details.coding = NOT_IMPLEMENTED
- details.text = <parameter-name> is an unrecognised parameter

Consumers MUST check for the presence of an OperationOutcome resource as described above to check for incomplete data as a result of unsupported parameters.

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
- OperationOutcome containing warnings about any unsupported parameters
- resources holding consultations, problems, immunisations, allergies, intolerance, medication and uncategorised data 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.