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 Access Record Structured 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://[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 | 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 |
Optional | 0..1 |
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 |
↳ 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 |
positiveInt |
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 |
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": "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"
}
}
]
}
]
}
Not permitted parameter combinations
Certain combinations of query parameters have the potential to introduce clinical risks. To prevent these scenarios occurring, the following combinations of parameters are not permitted and SHALL not be used by consumers:
When requesting consultations, the following part parameters MUST NOT be included:
includeMedications.medicationSearchFromDate
includeUncategorisedData.uncategorisedDataSearchPeriod
includeProblems.filterSignificance
includeProblems.filterStatus
When requesting problems, the following part parameters MUST NOT be included:
includeMedications.medicationSearchFromDate
includeUncategorisedData.uncategorisedDataSearchPeriod
In the event that one of the combinations of parameters are used in a request, an error MUST be raised as specified in the error handling table below. There are no restrictions on using combinations of top level parameters.
Examples of queries are available on the Search examples page.
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 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 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 |
A combination of parameters is included that isn’t permitted | 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/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
or not included: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 consultations- A
List
resource for each clinical area where data exists,Condition
,MedicationStatement
,MedicationRequest
with anintent
ofplan
andMedication
,AllergyIntolerance
,Observation - uncategorised
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:- A
List
resource for each area where data exists,MedicationStatement
,MedicationRequest
with anintent
ofplan
andMedication
,Immunization
,Observation - uncategorised
andCondition
resources representing the patient’s problems and all linked clinical information.
- A
-
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:- A
List
resource for each clinical area where data exists,Condition
andImmunization
resources representing the patient’s immunisations that have been given will be returned.
- A
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:- A
List
resource for each clinical area where data exists,Condition
andObservation - uncategorised
resources representing the patient’s uncategorised data will be returned.
- A
-
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
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
To illustrate how forwards compatibility works, the following example has been included: