Search loading...

API Hub

Explore and Make use of Nationally Defined Messaging APIs

 


Quick links

Go back to previous page

Migrate a patient's structured record

Migrate a patient's record in structured format

Use case

Migrate a patient’s record from one organisation to another in FHIR® structured format.

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

FHIR® absolute request

POST https://[proxy_server]/https://[structured_provider_server]/[structured_fhir_base]/Patient/$gpc.migratestructuredrecord

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.migratestructuredrecord-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.migratestructuredrecord-1

Authorisation

This interaction can only be used when patient’s information is being migrated between GP practices. When a request to migrate the patient’s record is made, the provider system MUST check that the consumer system is the patient’s registered GP practice by checking this against PDS. The following steps will need to be performed:

  • The consuming system will need to perform a PDS trace to retrieve the patient’s current registered practice
  • The consuming system MUST record the patient’s current registered practice
  • The consuming system updates PDS as the patient’s registered practice
  • The consuming system looks up the previously registered practice’s endpoint on SDS
  • The consuming system makes a request to migrate the patient’s record
  • The providing system MUST check that the ODS code supplied in the requesting_organization claim in the JWT matches the patient’s registered practice on PDS

Availability of data

The record migration use case requires that information is always available regardless of whether the structured capability has been enabled, or whether clinical areas have been turned off using configuration for clinical areas.

Payload request body

The payload request body comprises a Parameters resource, conforming to the GPConnect-MigrateStructuredRecord-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.
includeFullRecord Mandatory 1..1 Include the patient's full clinical record in the response.
  ↳ includeSensitiveInformation Boolean Mandatory 1..1 Include confidential and sensitive information in the response, this parameter has a default value of 'true'. This parameter can only be set to true if an appropriate `requested_scope` value is provided in the JWT, more guidance is available in the Cross-organisation audit and provenance page

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

The example below shows a fully populated Parameters resource as a request to the $gpc.migratestructuredrecord operation:

{
  "resourceType": "Parameters",
  "parameter": [
    {
      "name": "patientNHSNumber",
      "valueIdentifier": {
        "system": "https://fhir.nhs.uk/Id/nhs-number",
        "value": "9999999999"
      }
    },
    {
      "name": "includeFullRecord",
      "part": [
        {
          "name": "includeSensitiveInformation",
          "valueBoolean": true
        }
      ]
    }
  ]
}

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 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 ODS code in the JWT doesn’t match the ODS code for the patient’s registered practice on PDS NO_RELATIONSHIP
The JWT requested_scope is set to conf/N when a request has been made for sensitive information CONFLICTING_VALUES
The patient’s NHS number in the provider system is not associated with a NHS number status indicator code of ‘Number present and verified’ PATIENT_NOT_FOUND
The request is for a sensitive patient PATIENT_NOT_FOUND
A part parameter is passed without a value INVALID_PARAMETER
An unrecognised parameter is included in the request INVALID_PARAMETER

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 previously registered GP practice, where their record is being migrated from, 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 and diary entries 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.
Full record

Provider systems MUST include the following in the response Bundle:

Documents

DocumentReference resources containing document metadata including location will be returned as part of the response Bundle. Retrieval of these MUST be performed using the Migrate a document API in the Access Document capability.

All content is available under the Open Government Licence v3.0, except where otherwise stated