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:

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

API usage

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 SHALL include the following additional HTTP request headers:

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.

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

{
	"meta": {
		"profile": ["https://fhir.nhs.uk/STU3/OperationDefinition/GPConnect-GetStructuredRecord-Operation-1"]
	},
	"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": "medicationDatePeriod",
			"valuePeriod": {
				"start": "2017-06-04",
				"end": "2018-06-19"
			}
		}]
	}]
}

Error handling

The provider system SHALL 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.

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

Errors that may be encountered include:

• the patientNHSNumber parameter is not provided
• the patientNHSNumber is invalid, for example it fails format or check digit tests
• the patientNHSNumber has not been traced or cross-checked on PDS in the providing system
• a patient could not be found matching the patientNHSNumber provided
• an invalid medicationDatePeriod range is requested (that is, end date < start date)
• medicationDatePeriod.start or medicationDatePeriod.end contain a partial date, or have a value containing a time or offset component
• the includeAllergies parameter is passed without the corresponding includeResolvedAllergies part parameter
• the includeMedication parameter is passed without the corresponding includePrescriptionIssue part parameter
• the Parameters resource passed does not conform to that specified in the GPConnect-GetStructuredRecord-Operation-1 OperationDefinition
• the provider could not parse, or does not recognise a parameter name or value in the Parameters resource

Refer to Error handling guidance for further information including appropriate error codes.

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 SHALL:

• 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 and intolerance and medication information 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 SHALL NOT:

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

Allergies

Provider systems SHALL 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 SHALL 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 medicationDatePeriod parameter is set, the medication summary data SHALL be restricted to that whose date falls within (inclusive), or overlaps (in the case of a range), the Period.start and Period.end. Where only a start date is supplied, the medication summary data SHALL be restricted to that whose date is on or after Period.start. Where only and end date is supplied, the medication summary data SHALL be restricted to that whose date is on or before Period.start. The date used shall be:

    1 - effectiveDate or effectivePeriod

    • effectiveStartDate - the date the prescription (or cycle of prescriptions) is expected to start. For repeat and repeat dispensed prescriptions this is the period covered by the entire cycle of planned issues
    • effectiveEndDate - the date the prescription (or cycle of prescriptions) is expected to finish. For repeat and repeat dispensed prescriptions this is the period covered by the entire cycle of issue. Where this date is not supplied for a repeat dispensed prescription then they are considered ongoing until a date is supplied

    2 - dateAsserted, where the medication does not have an effectiveDate or effectivePeriod

  • 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

Bundle population illustrated

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

Payload response examples

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

• Allergies - FHIR examples
• Medication - FHIR examples