Retrieve a patient's record in structured format

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:

API usage

Interaction diagram

Get structured record 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 includeAllergies is set.

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 includeMedication is set.

  ↳ medicationSearchFromDate Date Optional 0..1 Restrict medications returned on or after the date specified. Rules:
  • If the medicationSearchFromDate is not specified, all medication will be returned.
  • If the medicationSearchFromDate is populated, all medications which are active on or after the medicationSearchFromDate MUST be returned.
  • medicationSearchFromDate MUST be populated with a date less than or equal to the current date.
  • medicationSearchFromDate MUST be populated with whole dates only (for example, 2017-02-01) - that is, no partial dates, or with a time period or offset.

Part parameter: may only be provided if includeMedication is set.

includeConsultations Optional 0..1 Include consultations in the response.
  ↳ consultationSearchPeriod Period Optional 0..1 Restrict consultations by defining a time period
  • If the consultationSearchPeriod is not specified, all consultations will be returned.
  • If the consultationSearchPeriod.start is populated, all consultations on or after the consultationSearchPeriod.start MUST be returned.
  • If the consultationSearchPeriod.end is populated, all consultations on or before the consultationSearchPeriod.end MUST be returned.
  • consultationSearchPeriod.start and consultationSearchPeriod.end MUST be populated with a date less than or equal to the current date.
  • consultationSearchPeriod.start and consultationSearchPeriod.end MUST be populated with whole dates only (for example, 2017-02-01) - that is, no partial dates, or with a time period or offset.

Part parameter: may only be provided if includeConsultations is set.

  ↳ includeNumberOfMostRecent positiveInt Optional 0..1 Limit the number of returned consultations

Part parameter: may only be provided if includeConsultations is set.

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 includeProblems is set.

  ↳ 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 includeProblems is set.

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 includeImmunisations is set.

  ↳ 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 includeImmunisations is set.

includeUncategorisedData Optional 0..1 Include uncategorised data in the response.
  ↳ uncategorisedDataSearchPeriod Period Optional 0..1 Restrict uncategorised data by defining a time period
  • If the uncategorisedDataSearchPeriod is not specified, all uncategorised data will be returned.
  • If the uncategorisedDataSearchPeriod.start is populated, all uncategorised data on or after the uncategorisedDataSearchPeriod.start MUST be returned.
  • If the uncategorisedDataSearchPeriod.end is populated, all uncategorised data on or before the uncategorisedDataSearchPeriod.end MUST be returned.
  • uncategorisedDataSearchPeriod.start and uncategorisedDataSearchPeriod.end MUST be populated with a date less than or equal to the current date.
  • uncategorisedDataSearchPeriod.start and uncategorisedDataSearchPeriod.end MUST be populated with whole dates only (for example, 2017-02-01) - that is, no partial dates, or with a time period or offset.

Part parameter: may only be provided if includeUncategorisedData is set.

includeInvestigations Optional 0..1 Include investigations in the response.
  ↳ investigationSearchPeriod Period Optional 0..1 Restrict test results by defining a time period
  • If the investigationSearchPeriod is not specified, all test results will be returned.
  • If the investigationSearchPeriod.start is populated, all test results on or after the investigationSearchPeriod.start MUST be returned.
  • If the investigationSearchPeriod.end is populated, all test results on or before the investigationSearchPeriod.end MUST be returned.
  • investigationSearchPeriod.start and investigationSearchPeriod.end MUST be populated with a date less than or equal to the current date.
  • investigationSearchPeriod.start and investigationSearchPeriod.end MUST be populated with whole dates only (for example, 2017-02-01) - that is, no partial dates, or with a time period or offset.

Part parameter: may only be provided if includeInvestigations is set.

includeReferrals Optional 0..1 Include referrals in the response.
  ↳ referralSearchPeriod Period Optional 0..1 Restrict referrals by defining a time period
  • If the referralSearchPeriod is not specified, all referrals will be returned.
  • If the referralSearchPeriod.start is populated, all referrals on or after the referralSearchPeriod.start MUST be returned.
  • If the referralSearchPeriod.end is populated, all referrals on or before the referralSearchPeriod.end MUST be returned.
  • referralSearchPeriod.start and referralSearchPeriod.end MUST be populated with a date less than or equal to the current date.
  • referralSearchPeriod.start and referralSearchPeriod.end MUST be populated with whole dates only (for example, 2017-02-01) - that is, no partial dates, or with a time period or offset.

Part parameter: may only be provided if includeReferrals is set.

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:
  • If the diaryEntriesSearchDate is not specified, all diary entries will be returned.
  • If the diaryEntriesSearchDate is populated, all diary entries which occur on or before the diaryEntriesSearchDate MUST be returned.
  • diaryEntriesSearchDate MUST be populated with a date greater than or equal to the current date.
  • diaryEntriesSearchDate MUST be populated with whole dates only (for example, 2017-02-01) - that is, no partial dates, or with a time period or offset.

Part parameter: may only be provided if includeDiaryEntries is set.

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",
          "valueDate": 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": "filterSignificance",
          "valueCode": "major"
        }
      ]
    },
    {
      "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:

When requesting consultations, the following part parameters MUST NOT be included:

  • includeMedication.medicationSearchFromDate
  • includeUncategorisedData.uncategorisedDataSearchPeriod
  • includeProblems.filterSignificance
  • 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.

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 significance or 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 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
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 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)

    • 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 each clinical area referencing resources that have been returned
  • A List resource for secondary lists referencing resources contained in requested problems and consultations

  • MedicationStatement, MedicationRequest, Medication resources representing the patient’s medication
  • AllergyIntolerance resources representing the patient’s allergies and intolerances
  • List, Condition, Encounter, List - Consultation and Observation - narrative resources representing the patient’s consultations
  • Condition resources representing the patient’s problems
  • Immunization resources representing the patient’s immunisations
  • Observation - uncategorised and Observation - blood pressure resources representing the patient’s uncategorised data
  • DiagnosticReport, Observation - Test Group Header, Observation - Test Result, Observation - Filing Comments, ProcedureRequest, Specimen resources representing the patient’s test results
  • ReferralRequest resources representing the patient’s referrals will be returned.
  • ProcedureRequest resources representing the patient’s diary entries will be returned.
  • DocumentReference resources representing the patient’s documents.
    • 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 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
  • 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
  • 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:

  • A List resource for each clinical area referencing resources that have been returned
  • A List resource for secondary lists referencing resources contained in requested problems and consultations

  • MedicationStatement, MedicationRequest, Medication resources representing the patient’s medication
  • AllergyIntolerance resources representing the patient’s allergies and intolerances
  • Encounter resources representing the patient’s consultations
  • Condition resources representing the patient’s problems
  • Immunization resources representing the patient’s immunisations
  • Observation - uncategorised and Observation - blood pressure resources representing the patient’s uncategorised data
  • DiagnosticReport, Observation - Test Group Header, Observation - Test Result, Observation - Filing Comments, ProcedureRequest, Specimen resources representing the patient’s test results
  • ReferralRequest resources representing the patient’s referrals will be returned.
  • ProcedureRequest resources representing the patient’s diary entries will be returned.
  • DocumentReference resources representing the patient’s documents.

  • and when the filterStatus parameter is set:

    • problems with a clinicalStatus matching the parameter value and all linked clinical information.
  • and when the filterSignificance parameter is set:

    • problems with a problemSignificance matching the parameter value and all linked clinical information
  • Organization, Practitioner and PractitionerRole 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 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:

  • when the uncategorisedDataSearchPeriod 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:

  • 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:

  • when the referralSearchPeriod 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:

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

Search date: 15/01/2018 Current date: 08/10/2018
click image for full size view
Search date: 01/03/2018 Current date: 08/10/2018
click image for full size view
Search date: 08/07/2018 Current date: 08/10/2018
click image for full size view
Search date: 08/10/2018 Current date: 08/10/2018
click image for full size view


Bundle population illustrated

The following diagram illustrates the population of the response Bundle according to the parameters in the inbound Parameters request resource:

Structured Bundle response

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: