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
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 |
includeMedication |
|
Optional | Include medication in the response. |
↳ includePrescriptionIssues |
Boolean |
Mandatory |
Include each prescription issue in the response.
Part parameter: may only be provided if |
↳ medicationSearchFromDate |
Date |
Optional |
Restrict medications returned on or after the date specified. Rules:
Part parameter: may only be provided if |
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 |
The provider could not parse, or does not recognise a parameter name or value in 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 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 theGPConnect-StructuredRecord-Bundle-1
profile definition - return the following resources in the
Bundle
:Patient
matching the NHS Number sent in the body of the requestOrganization
matching the patient’s registered GP practice, referenced fromPatient.generalPractitioner
Organization
matching the organisation serving the request, if different from above, referenced fromPatient.managingOrganization
Practitioner
matching the patient’s usual GP, if they have one, referenced fromPatient.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 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 tofalse
:List
andAllergyIntolerance
resources representing the patient’s allergies and intolerances, excluding those marked as resolved or ended
-
and when the
includeResolvedAllergies
parameter is set totrue
:List
andAllergyIntolerance
resources representing the patient’s allergies and intolerances, including those marked as resolved or ended
-
-
Organization
,Practitioner
andPractitionerRole
resources that are referenced by theAllergyIntolerance
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 anintent
ofplan
andMedication
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
andeffective.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
- an acute medication is considered active on its
- when a medication does not have an
- A medication is considered active between its
- all medications which are active on or after the
-
and when the
includePrescriptionIssues
parameter is set tofalse
:- no prescription issue information should be returned
-
and when the
includePrescriptionIssues
parameter is set totrue
:MedicationRequest
resources with anintent
oforder
representing the patient’s prescription issues, for the above medication summary data
-
-
Organization
,Practitioner
andPractitionerRole
resources that are referenced by theMedicationStatement
andMedicationRequest
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:
Payload response examples
Examples of the payload requests and responses can be found here: