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:

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://[structured_provider_server]/[structured_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 Optional Include each prescription issue in the response, this parameter has a default value of 'true'. More guidance relating to its use is available in the Medication guidance page

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.

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": "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 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
A part parameter is passed without a value INVALID_PARAMETER
GP Connect is not enabled at the practice (see Enablement) ACCESS_DENIED
The Access Record Structured capability is not enabled at the practice (see Enablement) ACCESS_DENIED 
{
  "name": "includeProblems"
}

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 or not included:

      • 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
click image for full size view
Search date: 01/03/2018 Current date: 08/10/2018
click image for full size view
Search date: 08/07/2018 Current date: 08/10/2018
click image for full size view
Search date: 08/10/2018 Current date: 08/10/2018
click image for full size view

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: