Use case
Retrieve a patient’s record in FHIR® structured format from a GP practice. Full details of the use cases are available on the Business Requirements page.
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 | 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 |
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 |
↳ medicationSearchFromDate |
Date |
Optional | 0..1 |
Restrict medications returned on or after the date specified. Rules:
Part parameter: may only be provided if |
includeConsultations |
|
Optional | 0..1 | Include consultations in the response. |
↳ consultationSearchPeriod |
Period |
Optional | 0..1 |
Restrict consultations by defining a time period
Part parameter: may only be provided if |
↳ includeNumberOfMostRecent |
Integer |
Optional | 0..1 |
Limit the number of returned consultations
Part parameter: may only be provided if |
includeProblems |
|
Optional | 0..* | Include problems in the response. This is a repeating parameter with each repetition representing a pair of problem significance and status values. |
↳ filterStatus |
Code |
Optional | 0..1 |
Restrict the problems that are returned by their clinical status. Valueset: http://hl7.org/fhir/stu3/valueset-condition-clinical.html Values MUST be `active` or `inactive` Part parameter: may only be provided if |
↳ filterSignificance |
Code |
Optional | 0..1 |
Restrict the problems that are returned by their clinical significance Valueset: ValueSet-CareConnect-ProblemSignificance-1 Part parameter: may only be provided if |
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
Part parameter: may only be provided if |
includeInvestigations |
|
Optional | 0..1 | Include investigations in the response. |
↳ investigationSearchPeriod |
Period |
Optional | 0..1 |
Filter the investigations to match the specified period
Part parameter: may only be provided if |
includeReferrals |
|
Optional | 0..1 | Include referrals in the response. |
↳ referralSearchPeriod |
Period |
Optional | 0..1 |
Restrict referrals by defining a time period
Part parameter: may only be provided if |
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.
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": "includeNumberOfMostRecent",
"valueInteger": "3"
}
]
},
{
"name": "includeProblems",
"part": [
{
"name": "filterStatus",
"valueCode": "active"
},
{
"name": "filterSignificance",
"valueCode": "major"
}
]
},
{
"name": "includeImmunisations"
},
{
"name": "includeUncategorisedData",
"part": [
{
"name": "uncategorisedDataSearchPeriod",
"valuePeriod": {
"start": "2016-12-25",
"end": "2018-12-25"
}
}
]
},
{
"name": "includeInvestigations",
"part": [
{
"name": "investigationSearchPeriod",
"valuePeriod": {
"start": "2017-01-02",
"end": "2017-07-02"
}
}
]
},
{
"name": "includeReferrals",
"part": [
{
"name": "referralSearchPeriod",
"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 fields is corrupt or a specific business rule/constraint is breached.
The table below shows 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 |
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 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 start date of the consultationSearchPeriod part parameter is greater than the end 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 filterStatus part parameter contains a value other than active or inactive |
INVALID_PARAMETER |
The filterSignificance part parameter contains a value other than major or minor |
INVALID_PARAMETER |
The investigationSearchPeriod parameter value contains a partial date, or has a value containing a time or offset component |
INVALID_PARAMETER |
The referralSearchPeriod part parameter is greater than the current date |
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/fhir+json; 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 consultations, problems, immunisations, allergies, intolerance, medications, uncategorised data and warnings about unsupported parameters 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
,Condition
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
,Condition
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
,Condition
,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
Consultations
Provider systems MUST include the following in the response Bundle
:
-
when the
includeConsultations
parameter is not set:- no consultation information shall be returned
- when the
includeConsultations
parameter is set:List
,Condition
,Encounter
,List - Consultation
andObservation - narrative
resources representing the patient’s consultationsList
,Condition
,MedicationStatement
,MedicationRequest
with anintent
ofplan
andMedication
,AllergyIntolerance
,Observation - uncategorised
,DocumentReference
andImmunization
resources for linked clinical information- and when the
numberOfMostRecent
parameter is set:- limit the number of returned consultations to match the included value
- when the
consultationSearchPeriod
is set:- when a
start
value is set, all consultations with anEncounter.period.start
after the date MUST be returned - and when an
end
value is set, all consultations with anEncounter.period.end
before the date MUST be returned - and when both a
start
andend
are specified, consultations with anEncounter.period.start
after thestart
and anEncounter.period.end
before theend
MUST be returned
- when a
- when the
includeNumberOfMostRecent
is set:- consultations MUST be ordered by
Encounter.period.start
descending - and the number of most recent consultations matching the parameter value MUST be returned
- consultations MUST be ordered by
Problems
Provider systems MUST include the following in the response Bundle
:
-
when the
includeProblems
parameter is not set:- no problem information shall be returned
-
when the
includeProblems
parameter is set:List
,MedicationStatement
,MedicationRequest
with anintent
ofplan
andMedication
,Immunization
,Observation - uncategorised
,DocumentReference
andCondition
resources representing the patient’s problems and all linked clinical information.
-
and when the
filterStatus
parameter is set:- problems with a
clinicalStatus
matching the parameter value and all linked clinical information.
- problems with a
-
and when the
filterSignificance
parameter is set:- problems with a
problemSignificance
matching the parameter value and all linked clinical information
- problems with a
Immunisations
Provider systems MUST include the following in the response Bundle
:
-
when the
includeImmunisations
parameter is not set:- no immunisation information shall be returned
-
when the
includeImmunisations
parameter is set:List
,Condition
andImmunization
resources representing the patient’s immunisations will be returned.
Uncategorised data
Provider systems MUST include the following in the response Bundle
:
-
when the
includeUncategorisedData
parameter is not set:- no uncategorised data shall be returned
-
when the
includeUncategorisedData
parameter is set:List
,Condition
andObservation - uncategorised
resources representing the patient’s uncategorised data will be returned.
-
when the
uncategorisedDataSearchPeriod
is set:- when a
start
value is set, all uncategorised data with anObservation.effectiveTime
after the date MUST be returned - and when an
end
value is set, all uncategorised data with anObservation.effectiveTime
before the date MUST be returned - and when both a
start
andend
are specified, uncategorised data with anObservation.effectiveTime
after thestart
and with anObservation.effectiveTime
before theend
MUST be returned
- when a
Investigations
Provider systems MUST include the following in the response Bundle
:
-
when the
includeInvestigations
parameter is not set:- no investigations shall be returned
-
when the
includeInvestigations
parameter is set:-
DiagnosticReport
,Observation - Test Group Header
,Observation - Test Result
,Observation - Filing Comments
,ProcedureRequest
,Specimen
,DocumentReference
andCondition
resources representing the patient’s test results -
and when the
investigationSearchPeriod
parameter is set:- when a
start
value is set, all investigations with aDiagnosticReport.issued
after the date MUST be returned - and when an
end
value is set, all investigations with aDiagnosticReport.issued
before the date MUST be returned - and when both a
start
andend
are specified, investigations with aDiagnosticReport.issued
after thestart
and before theend
MUST be returned
- when a
-
-
Organization
,Practitioner
andPractitionerRole
resources that are referenced by the resources above
Referrals
Provider systems MUST include the following in the response Bundle
:
-
when the
includeReferrals
parameter is not set:- no referrals information shall be returned
-
when the
includeReferrals
parameter is set:List
,ReferralRequest
andCondition
resources representing the patient’s referrals will be returned.
-
when the
referralSearchPeriod
is set:- when a
start
value is set, all referrals with aReferralRequest.authoredOn
after the date MUST be returned - and when an
end
value is set, all referrals with aReferralRequest.authoredOn
before the date MUST be returned - and when both a
start
andend
are specified, referrals with aReferralRequest.authoredOn
after thestart
and with aReferralRequest.authoredOn
before theend
MUST be returned
- when a
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:
- Allergies - FHIR® examples
- Medication - FHIR® examples
- Consultations and problems - FHIR® examples
- Immunizations - FHIR® examples
- Uncategorised data - FHIR® examples
- Investigations - FHIR® examples
To illustrate how forwards compatibility works, the following example has been included: