GP Connect - Access Record Structured

This guidance is under active development by NHS Digital and content may be added or updated on a regular basis.

Retrieve a patient's structured record

Use case

Retrieve a patient’s record in FHIR® structured format from a GP practice.

API specification

See API specification for more details about topic such as:

  • Who can use the API
  • Related APIs
  • API status and roadmap
  • Service level
  • Security and authorisation
  • Environments and testing
  • Onboarding
  • Error handling

Interaction diagram

get-structured-record-interaction-diagram

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 the GPConnect-StructuredRecord-Bundle-1 profile definition
  • return the following resources in the Bundle:
    • Patient matching the NHS Number sent in the body of the request
    • Organization matching the patient’s registered GP practice, referenced from Patient.generalPractitioner
    • Organization matching the organisation serving the request, if different from above, referenced from Patient.managingOrganization
    • Practitioner matching the patient’s usual GP, if they have one, referenced from Patient.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 to false:
  • and when the includeResolvedAllergies parameter is set to true:
  • Organization, Practitioner and PractitionerRole resources that are referenced by the   AllergyIntolerance 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 referencing MedicationStatement resources that match the supplied query parameters
  • A List resource referencing Condition resources that are linked from the returned MedicationStatement resources
  • Condition, MedicationStatement, MedicationRequest with an intent of plan and   Medication 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 and effective.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
  • all medications that are prescribed elsewhere will be returned regardless of the medicationSearchFromDate
  • and when the includePrescriptionIssues parameter is set to false:
    • no prescription issue information should be returned
  • and when the includePrescriptionIssues parameter is set to true or not included:
    • MedicationRequest resources with an intent of order representing the patient’s prescription issues, for the above medication summary data
  • Organization, Practitioner and PractitionerRole resources that are referenced by the   MedicationStatement and   MedicationRequest 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 referencing Encounter resources that match the supplied query parameters
  • A List resource of secondary lists referencing resources that are linked from the returned Encounter resources
  • For each Encounter referenced in the List resource:
  • and when the consultationSearchPeriod parameter is set:
    • when a start value is set, all consultations with an Encounter.period.start after the date MUST be returned
    • and when an end value is set, all consultations with an Encounter.period.end before the date MUST be returned
    • and when both a start and end are specified, consultations with an Encounter.period.start after the start and an Encounter.period.end before the end MUST be returned
  • and when the includeNumberOfMostRecent parameter 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
  • Organization, Practitioner, PractitionerRole and Location 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:

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 referencing Immunization resources that match the supplied query parameters
  • A List resource referencing Condition resources that are linked from the returned Immunization resources
  • Condition and Immunization resources representing the patient’s immunisations that have been given will be returned.
  • and when the includeNotGiven part parameter is set to false or not supplied:
    • only immunisations where notGiven is set to false shall be returned
  • and when the includeNotGiven part parameter is set to true
    • all immunisations where notGiven is set to true or false shall be returned
  • and when the includeStatus part parameter is set to false:
    • only immunisations will be returned
  • and when the includeStatus part parameter is set to true or not supplied:
  • Organization, Practitioner, PractitionerRole and Location 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 referencing Observation - uncategorised resources that match the supplied query parameters
  • A List resource referencing Condition resources that are linked from the returned Observation - uncategorised resources
  • Condition, Observation - uncategorised and Observation - 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 an Observation.effectiveTime after the date MUST be returned
    • and when an end value is set, all uncategorised data with an Observation.effectiveTime before the date MUST be returned
    • and when both a start and end are specified, uncategorised data with an Observation.effectiveTime after the start and with an Observation.effectiveTime before the end MUST be returned
  • Organization, Practitioner and PractitionerRole 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 referencing DiagnosticReport resources that match the supplied query parameters
  • A List resource referencing Condition resources that are linked from the returned DiagnosticReport resources
  • DiagnosticReport, Observation - Test Group Header, Observation - Test Result, Observation - Filing Comments, ProcedureRequest, Specimen and   Condition resources representing the patient’s test results
  • and when the investigationSearchPeriod parameter is set:
    • when a start value is set, all investigations with a DiagnosticReport.issued after the date MUST be returned
    • and when an end value is set, all investigations with a DiagnosticReport.issued before the date MUST be returned
    • and when both a start and end are specified, investigations with a DiagnosticReport.issued after the start and before the end MUST be returned
  • Organization, Practitioner and PractitionerRole 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 referencing ReferralRequest resources that match the supplied query parameters
  • A List resource referencing Condition resources that are linked from the returned ReferralRequest resources
  • ReferralRequest, Condition and DocumentReference 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 a ReferralRequest.authoredOn after the date MUST be returned
    • and when an end value is set, all referrals with a ReferralRequest.authoredOn before the date MUST be returned
    • and when both a start and end are specified, referrals with a ReferralRequest.authoredOn after the start and with a ReferralRequest.authoredOn before the end MUST be returned
  • Organization, Practitioner, PractitionerRole and HealthcareService 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 referencing ProcedureRequest resources that match the supplied query parameters
  • A List resource referencing Condition resources that are linked from the returned ProcedureRequest resources
  • ProcedureRequest and Condition 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
  • Organization, Practitioner and PractitionerRole 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.

Scenario 1

Search date: 15/01/2018

Current date: 08/10/2018

data_filter_scenario1

Scenario 2

Search date: 01/03/2018

Current date: 08/10/2018

data_filter_scenario2

Scenario 3

Search date: 08/07/2018

Current date: 08/10/2018

data_filter_scenario3

Scenario 4

Search date: 08/10/2018

Current date: 08/10/2018

data_filter_scenario4

Bundle population illustrated

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 below.

structured-bundle-response

Consumer systems MUST NOT rely on order or index of elements within the Bundle resource in order to parse encapsulated resources.

Payload response examples

Examples of the payload requests and responses can be found here:

To illustrate how forwards compatibility works, the following example has been included:

back to top