FHIR Get Structured Record API

This document specifies the technical details for accessing and using the Discovery Data Service FHIR® Care Connect API, for the use by interoperability system suppliers developing integrations against the service.

The Discovery Data Service (DDS) is an NHS owned service that provides low cost access to personal health and care data from combined primary, secondary, unscheduled and community health care data sets (https://discoverydataservice.org/Content/Overview.htm)

All data that is published or subscribed to and from DDS is governed by strict information governance rules and underpinned by Data Sharing Agreements, Sharing Flows and Subscriber Extract Projects (https://discoverydataservice.org/Content/Governance.htm)

DDS receives data from multiple source publishing systems in multiple formats and normalises the data into a common structure based on national care record standards.

DDS makes the data available to multiple subscribers in standardised formats, one of the common formats being FHIR®.

The Discovery FHIR CareConnect $getstructuredrecord API uses a secure authentication and authorisation service. This uses recommended standards for identity and access management, using OpenID Connect and OAuth 2.0 methods, and also includes an additional security layer, where DDS checks it’s internal User Management service to ensure that each user is authorised with the necessary role based access profiles to use each particular application. This allows for tokens and user access to be centrally managed and revoked within the DDS User Manager application.

The following FHIR CareConnect FHIR STU3 resources are currently supported by the API.

AllergyIntolerance, Condition, MedicationStatement, Medication, MedicationRequest, Observation, Organization, Patient, Practitioner, PractitionerRole, Encounter, EpisodeOfCare, DiagnosticReport, FamilyMemberHistory, Immunization, Location, Procedure, ProcedureRequest, ReferralRequest, RelatedPerson, Appointment.

Two API calls are used for the FHIR CareConnect $getstructuredrecord API:

• Authenticate
• Authorise/GetRecord

Authenticate

Authenticate the client identity by passing in client credentials to receive an access token for the API.

The Client Credentials grant is used when applications request an access token to access their own resources, not on behalf of a user.

The authorization server MUST authenticate the client.

https://devauthentication.discoverydataservice.net/authenticate/$gettoken

Passing this JSON POST body (no header required)

{
  "grantType": "client_credentials",
  "clientId": "fhir-api",
  "clientSecret": "6d8e1310-5e9c-4b62-b314-79fbd9c735d5"
}

The grantType parameter must be set to client_credentials.

Use 6d8e1310-5e9c-4b62-b314-79fbd9c735d5 as the client secret for demo purposes only; the client secret is unique to each client application and can be acquired by contacting the Discovery Data Service Helpdesk at info@discoverydataservice.org

If the access token request is valid and authorized, the authorization server issues an access token in this JSON reply, or a 404 HTTP Not Found (Unauthorized Client) response if the request failed client authentication or is invalid.

{
    "access_token": "xxxxxxxxxxxxxxxxxxx",
    "not-before-policy": 1548863201,
    "scope": "profile email",
    "token_type": "bearer",
    "session_state": "97260f48-23c4-408d-8af2-d528fc17390c",
    "expires_in": 60
}

NOTE: A refresh token SHOULD NOT and is not included, as specified in the OAuth 2.0 standards.

https://tools.ietf.org/html/rfc6749#section-4.4

Authorise/GetRecord

Retrieve a patient's structured care record as a FHIR bundle in the FHIR CareConnect STU3 format. See https://fhir.hl7.org.uk/

This call uses the access token from the authentication API to authorise the client's access to the API, which will return the FHIR bundle if the client is recognised and authorised to use this service.

https://devfhirapi.discoverydataservice.net:8443/fhirTestAPI/patient/$getstructuredrecord

Passing this JSON POST body

{
  "meta": {
    "profile": [
      "https://fhir.hl7.org.uk/STU3/OperationDefinition/CareConnect-GetStructuredRecord-Operation-1"
    ]
  },
  "resourceType": "Parameters",
  "parameter": [
    {
      "name": "patientNHSNumber",
      "valueIdentifier": {
        "system": "https://fhir.hl7.org.uk/Id/nhs-number",
        "value": "5558526785"
      }
    },
    {
      "name": "patientDOB",
      "valueIdentifier": {
        "system": "https://fhir.hl7.org.uk/Id/dob",
        "value": "1970-01-01"
      }
    }
  ]
}

Note: The patientDOB parameter is optional.

Set the Authorization header in the REST POST call to the value of the access_token returned from the authentication API.

Note: Access tokens expire if they are not used according to the value set in the expires_in attribute of the Client Credentials authentication method response.

If this API fails to authorise the access token against the Discovery identity and access management service, then an Unauthorised return value will be sent with a 401 HTTP Status (Unauthorized).

Success will return the FHIR bundle for the patient specified in the query parameters.

A list of NHS numbers that can be used in this Authorise/GetRecord paramaeter can be found here.

Workflow

Optional request parameters

The message body of the getRecord request can contain a number of optional parameters that change the behaviour of the API:

Date of birth

In addition to supplying an NHS number, you can optionally include the patient's date of birth by including the following parameter:

{
	"name": "patientDOB",
	"valueIdentifier": {
		"system": "https://fhir.hl7.org.uk/Id/dob",
		"value": "1970-01-01"
	}
}

We encourage the use of this parameter to provide additional assurance that the correct patient is being requested and returned; if the NHS number and date of birth do not match with a record in the DDS, no record will be returned.

Demographics only

You can restrict the data returned to only include patient demographic information instead of the full medical record; this can be requested by using the following parameter:

{
	"name": "demographicsOnly",
	"part": [
		{
			"name": "includeDemographicsOnly",
			"valueBoolean": true
		}
	]
}

Include inactive patients

By default the API will only return fully active and registered patients who are not marked as deceased. If your project requires access to inactive or deceased patients, and to include those patients in the results, the following parameter can be used:

{
	"name": "includeInactivePatients",
	"part": [
		{
			"name": "includeInactivePatients",
			"valueBoolean": true
		}
	]
}