Retrieve a patient’s structured record

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:

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

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.

Important: Consumer guidance: The parameters can be used together in a single call or in multiple calls so that information can be retrieved if required. It is advised that the number of requests that are made to retrieve a patient’s record are kept to a minimum.

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`

Important: The HL7 FHIR specification states that Parameters.parameter MUST have one of part, value or resource. However, in the case of Parameters which just have optional part parameters such as `includeProblems` it is valid to have no part parameters or value in a request. The following is an example of the `includeProblems` parameter with no part parameters:

{
  "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.