Use case for reading a patient resource

Prerequisites

Consumer

The consumer system:

• SHALL have previously resolved the organisation’s FHIR endpoint base URL through the Spine Directory Service
• SHALL have previously traced the patient’s NHS number using the Personal Demographics Service or an equivalent service
• SHALL have previously resolved the logical ID of the patient on the server using the NHS number

API use case

This specification describes a single use cases. For complete details and background, please see the Foundations Capability Bundle.

Security

• GP Connect utilises TLS Mutual Authentication for system level authorization
• GP Connect utilises a JSON Web Tokens (JWT) to transmit clinical audit and provenance details

API usage

Request operation

FHIR relative request

GET /Patient/[id]

FHIR absolute request

GET https://[proxy_server]/https://[provider_server]/[fhir_base]/Patient/[id]

Request headers

Consumers SHALL include the following additional HTTP request headers:

Header	Value
Ssp-TraceID	Consumer’s TraceID (i.e. GUID/UUID)
Ssp-From	Consumer’s ASID
Ssp-To	Provider’s ASID
Ssp-InteractionID	urn:nhs:names:services:gpconnect:fhir:rest:read:patient-1

Payload request body

N/A

Error handling

Provider systems:

• SHALL return a GPConnect-OperationOutcome-1 resource that provides additional detail when one or more data fields are corrupt or a specific business rule/constraint is breached.

  For example, the:

  • logical identifier of the resource is not valid/can’t be found on the server

  Refer to Development - FHIR API Guidance - Error Handling for details of error codes.

• SHALL return a PATIENT_NOT_FOUND error where a request for a PDS sensitive flagged patient is received. Please see Information governance for more information.

Request response

Response headers

Provider systems are not expected to add any specific headers beyond that described in the HTTP and FHIR® standards.

Payload response body

Provider systems:

• SHALL return a 200 OK HTTP status code on successful execution of the operation.

• SHALL return Patient resources that conform to the CareConnect-GPC-Patient-1 profile.

• SHALL populate the following fields:
  • meta.profile with the profile URI
  • versionId with the current version of the Patient resource.
  • identifier with relevant business identifiers, including a minimum of the patient’s NHS number
  • name
    • The patient resource SHALL contain a single instance of the name element with the use of official and SHALL contain the name synchronised with PDS.
  • birthDate
  • gender
  • address where available
  • telecom where available
  • contact with the patient’s contacts - see Patient.contact population for further details
  • registrationDetails.preferredBranchSurgery with a reference to a Location resource representing the patient’s preferred branch surgery (see Branch surgeries for more details)
  • nhsCommunication with the patient’s language information, where available
  • managingOrganization Note: this is the current organisation, as addressed by ODS code in the base URL, and NOT the patient’s registered practice which may be different

• SHALL meet General FHIR resource population requirements populating all fields where data is available, excluding those listed below

• SHALL NOT populate the following fields:
  • ethnicCategory
  • religiousAffiliation
  • patient-cadavericDonor
  • residentialStatus
  • treatmentCategory
  • birthPlace
  • maritalStatus
  • multipleBirthBoolean

{
  "resourceType": "Patient",
  "id": "2",
  "meta": {
    "versionId": "1469448000000",
    "profile": [
      "https://fhir.nhs.uk/STU3/StructureDefinition/CareConnect-GPC-Patient-1"
    ]
  },
  "extension": [
    {
      "url": "https://fhir.nhs.uk/STU3/StructureDefinition/Extension-CareConnect-GPC-RegistrationDetails-1",
      "extension": [
        {
          "url": "preferredBranchSurgery",
          "valueReference": {
            "reference": "Location/785b4ff5-aced-4bdf-b7ed-34f92131ce97"
          }
        }
      ]
    },
    {
      "url": "https://fhir.nhs.uk/STU3/StructureDefinition/Extension-CareConnect-GPC-NHSCommunication-1",
      "extension": [
        {
          "url": "language",
          "valueCodeableConcept": {
            "coding": [
              {
                "system": "https://fhir.nhs.uk/STU3/CodeSystem/CareConnect-HumanLanguage-1",
                "code": "bn",
                "display": "Bengali"
              }
            ]
          }
        },
        {
          "url": "interpreterRequired",
          "valueBoolean": false
        }
      ]
    }
  ],
  "identifier": [
    {
      "extension": [
        {
          "url": "https://fhir.nhs.uk/STU3/StructureDefinition/Extension-CareConnect-GPC-NHSNumberVerificationStatus-1",
          "valueCodeableConcept": {
            "coding": [
              {
                "system": "https://fhir.nhs.uk/CareConnect-NHSNumberVerificationStatus-1",
                "code": "01",
                "display": "Number present and verified"
              }
            ]
          }
        }
      ],
      "system": "https://fhir.nhs.uk/Id/nhs-number",
      "value": "9476719931"
    }
  ],
  "active": true,
  "name": [
    {
      "use": "official",
      "text": "JACKSON Jane (Miss)",
      "family": "Jackson",
      "given": [
        "Jane"
      ],
      "prefix": [
        "Miss"
      ]
    }
  ],
  "telecom": [
    {
      "system": "phone",
      "value": "01454587554",
      "use": "home"
    }
  ],
  "gender": "female",
  "birthDate": "1952-05-31",
  "address": [
    {
      "use": "home",
      "type": "physical",
      "line": [
          "Trevelyan Square",
          "Boar Ln"
      ],
      "city": "Leeds",
      "district": "West Yorkshire",
      "postalCode": "LS1 6AE"
    }
  ],
  "managingOrganization": {
    "reference": "Organization/14"
  }
}