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..1 | Include problems in the response. |
↳ 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 |
includeImmunisations |
|
Optional | 0..1 | Include immunisations in the response. |
↳ includeNotGiven |
Boolean |
Optional | 0..1 |
Only include immunisations that have been given in the response. The default value for this is false .
Part parameter: may only be provided if |
↳ includeStatus |
Boolean |
Optional | 0..1 |
Include information about consent and dissent for immunisations in the response. The default value for this is true .
Part parameter: may only be provided if |
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 |
Restrict test results by defining a time 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 |
includeDiaryEntries |
|
Optional | 0..1 | Include diary entries in the response. |
↳ diaryEntriesSearchDate |
Date |
Optional | 0..1 |
Restrict diary entries returned on or before the date specified. Rules:
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": "includePrescriptionIssues",
"valueBoolean": true
}
]
},
{
"name": "includeConsultations",
"part": [
{
"name": "consultationSearchPeriod",
"valuePeriod": {
"start": "2017-12-25",
"end": "2018-12-25"
}
},
{
"name": "includeNumberOfMostRecent",
"valuePositiveInt": 3
}
]
},
{
"name": "includeProblems",
"part": [
{
"name": "filterStatus",
"valueCode": "active"
}
]
},
{
"name": "includeImmunisations",
"part": [
{
"name": "includeNotGiven",
"valueBoolean": false
},
{
"name": "includeStatus",
"valueBoolean": false
}
]
},
{
"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"
}
}
]
},
{
"name": "includeDiaryEntries",
"part": [
{
"name": "diaryEntriesSearchDate",
"valueDate": "2017-06-04"
}
]
}
]
}
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 with the exception of the predefined searches listed as Predefined multi area searches for common use cases:
When requesting consultations, the following part parameters MUST NOT be included:
includeMedication.medicationSearchFromDate
includeUncategorisedData.uncategorisedDataSearchPeriod
includeProblems.filterStatus
includeReferrals.referralSearchPeriod
includeDiaryEntries.diaryEntriesSearchDate
includeImmunisations.includeNotGiven
includeImmunisations.includeStatus
When requesting problems, the following part parameters MUST NOT be included:
includeMedication.medicationSearchFromDate
includeUncategorisedData.uncategorisedDataSearchPeriod
includeReferrals.referralSearchPeriod
includeDiaryEntries.diaryEntriesSearchDate
includeImmunisations.includeNotGiven
includeImmunisations.includeStatus
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.
Related problem headers not returned due to search criteria
If a problem is related to another problem using the relatedProblemHeader
extension it is possible that the related problem header is not returned due to the restrictions of the search criteria. It is possible for many problems to be related to each other and if the user needs to fully understand the problem relationships these can be returned by requesting all problems. This is done by not specifying a filter for status and putting includeProblems
in the request. This will result in all problems recorded on the GP system being returned and will include all links between problems.
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 start date of the consultationSearchPeriod part parameter is greater than the current date |
INVALID_PARAMETER |
The end date of 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 start date of the uncategorisedDataSearchPeriod part parameter is greater than the current date |
INVALID_PARAMETER |
The end date of the uncategorisedDataSearchPeriod part parameter is greater than the current date |
INVALID_PARAMETER |
The start date of the uncategorisedDataSearchPeriod part parameter is greater than the end date |
INVALID_PARAMETER |
The filterStatus part parameter contains a value other than active or inactive |
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 |
The diaryEntriesSearchDate part parameter contains a partial date, or has a value containing a time or offset component |
INVALID_PARAMETER |
The diaryEntriesSearchDate part parameter is less than the current date |
INVALID_PARAMETER |
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, referrals, investigations, diary entries 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.
Unavailability of data
There are scenarios where requested clinical areas may not be returned, these are listed on the Configuration for supported clinical areas page along with guidance on implementation. Consumer systems MUST be able to handle this unavailability and warn users that some information hasn’t been returned.
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
:- A
List
resource referencingAllergyIntolerance
resources that match the supplied query parameters - A
List
resource referencingCondition
resources that are linked from the returnedAllergyIntolerance
resources Condition
andAllergyIntolerance
resources representing the patient’s allergies and intolerances, excluding those marked as resolved or ended
- A
- and when the
includeResolvedAllergies
parameter is set totrue
:- A
List
resource referencingAllergyIntolerance
resources that match the supplied query parameters - A
List
resource referencingCondition
resources that are linked from the returnedAllergyIntolerance
resources Condition
andAllergyIntolerance
resources representing the patient’s allergies and intolerances, including those marked as resolved or ended
- A
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:
- A
List
resource referencingMedicationStatement
resources that match the supplied query parameters - A
List
resource referencingCondition
resources that are linked from the returnedMedicationStatement
resources Condition
,MedicationStatement
,MedicationRequest
with anintent
ofplan
andMedication
resources representing the patient’s medication summary information (authorisations and medication prescribed elsewhere)- and 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
- all medications that are prescribed elsewhere will be returned regardless of the
medicationSearchFromDate
- 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:
- A
List
resource for referencingEncounter
resources that match the supplied query parameters - A
List
resource of secondary lists referencing resources that are linked from the returnedEncounter
resources - For each
Encounter
referenced in theList
resource:- The
Encounter
resource of the Consultation - The
List
resources that describe the structure of the Consultation - The
ProblemHeader (Condition)
resource of any directly linked Problems - The
MedicationRequest
,MedicationStatement
andMedication
resources of any linked Medications or Medical Devices- Always include the
MedicationStatement
,MedicationRequest
, (intent = plan) andMedication
resources - Only include
MedicationRequest
(intent = order) for directly linked issues - Include the
ProblemHeader (Condition)
resource of any Problems linked to the returned Medications and Medical Devices
- Always include the
- The
AllergyIntolerance
resource of any linked Allergies, including resolved allergies- Include the
ProblemHeader (Condition)
resource of any Problems linked to the returned Allergies
- Include the
- The
Immunization
resource of any linked Immunisations- Include the
ProblemHeader (Condition)
resource of any Problems linked to the returned Immunisations
- Include the
- The
Observation - uncategorised
resource of any linked Uncategorised Data- Include the
ProblemHeader (Condition)
resource of any Problems linked to the returned Uncategorised Data
- Include the
- The
ReferralRequest
resource of any linked Referrals- Include the
ProblemHeader (Condition)
resource of any Problems linked to the returned Referrals
- Include the
- The
DocumentReference
resource of any linked Documents- Only include the document metadata in any returned
DocumentReference
resource, do not include the binary file - In order to retrieve the binary file, a consumer must have been assured for the Access Document capability
- Include the
ProblemHeader (Condition)
resource of any Problems linked to the returned Documents
- Only include the document metadata in any returned
- The
DiagnosticReport
,ProcedureRequest
,Observation
,Specimen
andDocumentReference
resources of any linked Investigations- Only include the document metadata in any returned
DocumentReference
resource, do not include the binary file. - Include the
ProblemHeader (Condition)
resource of any Problems linked to the returned Investigation
- Only include the document metadata in any returned
- The
ProcedureRequest
resource of any linked Diary Entries- Include the
ProblemHeader (Condition)
resource of any Problems linked to the returned Diary Entries
- Include the
- The
- and when the
consultationSearchPeriod
parameter 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
- and when the
includeNumberOfMostRecent
parameter is set:- consultations MUST be ordered by
Encounter.period.start
descending
- consultations MUST be ordered by
- and the number of most recent consultations matching the parameter value MUST be returned
Organization
,Practitioner
,PractitionerRole
andLocation
resources that are referenced by the above resources that represent the consultation and its linked information
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 containing references toProblemHeader (Condition)
for every Problem that met the search criteria - A
List
resource containing references toProblemHeader (Condition)
for every Problem not meeting the search criteria but directly linked to a Problem which does meet the search criteria - A
List
resource of secondary lists referencing resources that are linked from the returnedEncounter
resources - For each
ProblemHeader (Condition)
referenced in theList
resource:- The
ProblemHeader (Condition)
resource of the Problem - The
ProblemHeader (Condition)
resources of any directly linked Problems - The
Encounter
resources of any linked Consultations - The
MedicationRequest
,MedicationStatement
, andMedication
resources of any linked Medications or Medical Devices- Always include the
MedicationStatement
,MedicationRequest
(intent = plan) andMedication
resources - Only include
MedicationRequest
(intent = order) for directly linked issues
- Always include the
- The
AllergyIntolerance
resource of any linked Allergies- Include the
ProblemHeader (Condition)
resource of any Problems linked to the returned Allergies
- Include the
- The
Immunization
resource of any linked Immunisations- Include the
ProblemHeader (Condition)
resource of any Problems linked to the returned Immunisations
- Include the
- The
Observation - uncategorised
resource of any linked Uncategorised Data- Include the
ProblemHeader (Condition)
resource of any Problems linked to the returned Uncategorised Data
- Include the
- The
ReferralRequest
resource of any linked Referrals- Include the
ProblemHeader (Condition)
resource of any Problems linked to the returned Referrals
- Include the
- The
DocumentReference
resource of any linked Documents- Only include the document metadata in any returned
DocumentReference
resource, do not include the binary file. - In order to retrieve the binary file, a consumer must have been assured for the Access Document capability
- Include the
ProblemHeader (Condition)
resource of any Problems linked to the returned Documents
- Only include the document metadata in any returned
- The
DiagnosticReport
,ProcedureRequest
,Observation
,Specimen
andDocumentReference
resources of any linked Investigations- Only include the document metadata in any returned
DocumentReference
resource, do not include the binary file. - Include the
ProblemHeader (Condition)
resource of any Problems linked to the returned Investigation - Where an
Observation
that represents a test or test group header has been made the actual problem then the ‘diagnosticReport’ it is from MUST be linked to the problem in therelatedClinicalContent
extension.
- Only include the document metadata in any returned
- The
ProcedureRequest
resource of any linked Diary Entries- Include the
ProblemHeader (Condition)
resource of any Problems linked to the returned Diary Entries
- Include the
- The
- and when the
filterStatus
parameter is set:- problems with a
clinicalStatus
matching the parameter value and all linked clinical information.
- problems with a
Organization
,Practitioner
andPractitionerRole
resources that are referenced by the above resources that represent the problem and its linked information
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 referencingImmunization
resources that match the supplied query parameters - A
List
resource referencingCondition
resources that are linked from the returnedImmunization
resources Condition
andImmunization
resources representing the patient’s immunisations that have been given will be returned.- and when the
includeNotGiven
part parameter is set tofalse
or not supplied:- only immunisations where
notGiven
is set tofalse
shall be returned
- only immunisations where
- and when the
includeNotGiven
part parameter is set totrue
- all immunisations where
notGiven
is set totrue
orfalse
shall be returned
- all immunisations where
- and when the
includeStatus
part parameter is set tofalse
:- only immunisations will be returned
- and when the
includeStatus
part parameter is set totrue
or not supplied:Observation - uncategorised
resources representing the status of patient’s immunisations will also be returned.
Organization
,Practitioner
,PractitionerRole
andLocation
resources that are referenced by the above resources that represent the immunization and its linked information
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 referencingObservation - uncategorised
resources that match the supplied query parameters - A
List
resource referencingCondition
resources that are linked from the returnedObservation - uncategorised
resources Condition
,Observation - uncategorised
andObservation - blood pressure
resources representing the patient’s uncategorised data will be returned.- and when the
uncategorisedDataSearchPeriod
parameter 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
Organization
,Practitioner
andPractitionerRole
resources that are referenced by the above resources that represent the uncategorised data and its linked information
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:
- A
List
resource referencingDiagnosticReport
resources that match the supplied query parameters - A
List
resource referencingCondition
resources that are linked from the returnedDiagnosticReport
resources DiagnosticReport
,Observation - Test Group Header
,Observation - Test Result
,Observation - Filing Comments
,ProcedureRequest
,Specimen
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 above resources that represent the uncategorised data and its linked information
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:
- A
List
resource referencingReferralRequest
resources that match the supplied query parameters - A
List
resource referencingCondition
resources that are linked from the returnedReferralRequest
resources ReferralRequest
,Condition
andDocumentReference
resources representing the patient’s referrals will be returned.- and when the
referralSearchPeriod
parameter 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
Organization
,Practitioner
,PractitionerRole
andHealthcareService
resources that are referenced by the above resources that represent the referral and its linked information
Diary entries
Provider systems MUST include the following in the response Bundle
.
When the includeDiaryEntries
parameter is not set:
- no diary entries shall be returned
When the includeDiaryEntries
parameter is set:
- A
List
resource referencingProcedureRequest
resources that match the supplied query parameters - A
List
resource referencingCondition
resources that are linked from the returnedProcedureRequest
resources ProcedureRequest
andCondition
resources representing the patient’s diary entries will be returned.- and when the
diaryEntriesSearchDate
parameter is set:- all diary entries that occur on or before the
diaryEntriesSearchDate
MUST be returned
- all diary entries that occur on or before the
Organization
,Practitioner
andPractitionerRole
resources that are referenced by the above resources that represent the diary entry and its linked information
Unknown and partial date handling in searches
Where parameters contain part parameters for date searches, the following SHALL apply:
- clinical information where an effective date is unknown or not recorded shall be returned alongside information that matches the supplied dates
- where partial dates have been recorded, they will be evaluated against the supplied dates in the following way:
- Dates with only the year specified are equivalent to an interval that starts on the first instant of January 1st and ends on the last instant of December 31st
- Dates with only the year and month specified are equivalent to an interval that starts at the first instant of the first day of the month and ends on the last instant of the last day of the month
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
- Referrals - FHIR® examples
- Diary entries - FHIR® examples
To illustrate how forwards compatibility works, the following example has been included: