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:
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 |
Boolean |
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 |
Boolean |
Optional | Include medication in the response. |
↳ includePrescriptionIssues |
Boolean |
Mandatory |
Include each prescription issue in the response.
Part parameter: may only be provided if |
↳ medicationDatePeriod |
Period |
Optional |
Restrict medication returned to that within the date period 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:
{
"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
ormedicationDatePeriod.end
contain a partial date, or have a value containing a time or offset component- the
includeAllergies
parameter is passed without the correspondingincludeResolvedAllergies
part parameter - the
includeMedication
parameter is passed without the correspondingincludePrescriptionIssue
part parameter - the
Parameters
resource passed does not conform to that specified in the GPConnect-GetStructuredRecord-Operation-1OperationDefinition
- 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 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:
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 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 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 anintent
ofplan
andMedication
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), thePeriod.start
andPeriod.end
. Where only a start date is supplied, the medication summary data SHALL be restricted to that whose date is on or afterPeriod.start
. Where only and end date is supplied, the medication summary data SHALL be restricted to that whose date is on or beforePeriod.start
. The date used shall be:1 -
effectiveDate
oreffectivePeriod
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 issueseffectiveEndDate
- 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 aneffectiveDate
oreffectivePeriod
-
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
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: