Skip to main content
Creating a new NHS England: NHS England and NHS Digital merged on 1 February 2023. More about the merger.

COVID-19 Medical Exemptions - FHIR API

Access a patient’s coronavirus (COVID-19) medical exemption status.

This specification is written from an OAS file.

This API is in production but internal, meaning the API is not currently available for integration by external third parties. If you want to use it, contact us and we'll look at making it available.

Overview

Use this API to access a patient’s coronavirus (COVID-19) medical exemption status.

You can:

  • get a patient's COVID-19 medical exemption status, based on their NHS number

You get the following data:

  • current COVID-19 medical exemption status
  • embedded Patient demographic details, including date of birth.

The patient demographic details might differ from those held in the Personal Demographics Service (PDS). To get demographic details from PDS, use the Personal Demographics Service FHIR API.

Data standards

This API uses the FHIR standard, and includes the resources:

It references resources:

Data availability, timing and quality

All exemption records are verified to ensure the NHS number is correct before making them available via the API.

In most cases this is automatic, and the record is available within 48 hours of the exemption being recorded, sometimes sooner.

Where automated NHS number verification fails, we verify the NHS number manually, which can take longer.

In a very small number of cases, we are unable to verify the NHS number, and we do not make the medical exemption available at all.


Who can use this API

This API:

  • is only for use by patient-facing applications
  • is only for non-clinical use
  • can only be used where there is a legal basis to do so

Make sure you have a valid use case before you go too far with your development. To do this, contact us.

You must do this before you can go live (see ‘Onboarding’ below).


API status and roadmap

This API is in production but internal, meaning the API is not currently available for integration by external third parties. If you want to use it, contact us and we'll look at making it available.

To see our roadmap, or to suggest, comment or vote on features for this API, see our interactive product backlog.


Technology

This API is RESTful.

It conforms to the FHIR global standard for health care data exchange, specifically to FHIR R4 (v4.0.1), except that it does not support the capabilities interaction.

It includes some country-specific FHIR extensions, which conforms to FHIR UK Core, specifically fhir.r4.ukcore.stu1 0.5.1.

You do not need to know much about FHIR to use this API - FHIR APIs are just RESTful APIs that follow specific rules. In particular:

  • resource names are capitalised and singular, and use US spellings, for example /QuestionnaireResponse not /questionnaireresponse
  • array names are singular, for example entry not entries for address lines
  • data items that are country-specific and thus not included in the FHIR global base resources are usually wrapped in an extension object

There are libraries and SDKs available to help with FHIR API integration.


Network access

This API is available on the internet and, indirectly, on the Health and Social Care Network (HSCN).

For more details see Network access for APIs.


Security and authorisation

This API has two access modes:

  • application-restricted access
  • user-restricted access

Application-restricted access

This access mode is application-restricted, meaning we authenticate the calling application but not the end user.

To use this access mode, use the following security pattern:

User-restricted access

Use this user-restricted access mode if the end user is a patient:

  • the end user must have their identity verified to 'high' (P9) level
  • the NHS number in the request must match the NHS number in the NHS login account

To use this access mode, use the following security pattern:


Environments and testing

Environment Base URL
Sandbox https://sandbox.api.service.nhs.uk/covid-medical-exemptions/FHIR/R4
Integration test https://int.api.service.nhs.uk/covid-medical-exemptions/FHIR/R4
Production https://api.service.nhs.uk/covid-medical-exemptions/FHIR/R4

Sandbox testing

Our sandbox environment:

  • is for early developer testing
  • only covers a limited set of scenarios
  • is open access, so does not allow you to test authorisation

For details of sandbox test scenarios, or to try out the sandbox using our 'Try this API' feature, see the documentation for each endpoint.

Alternatively, you can try out the sandbox using our Postman collection:

Integration testing

Our integration test environment:

  • is for formal integration testing
  • includes authorisation

Currently, the integration test environment returns a single static response, the same one as the sandbox environment - regardless of what request parameters you send. In due course we will change it to support more scenarios.

For more details see integration testing with our RESTful APIs.


Onboarding

  1. Complete an application through https://portal.developer.nhs.uk/ to the developer environment
    1. The DDA team will approve access through the portal. The portal will provide credentials.
  2. Onboard using the Supplier Conformance Assessment List (SCAL) process to confirm the use case and identify which API's access needs to be granted for
    1. The Direct Data Access team as the API producer will be notified as part of the review team
    2. The DDA team will contact you to confirm any details needed before permission can be granted
  3. Complete an application through https://portal.developer.nhs.uk/ to the live environment
    1. The DDA team will approve access through the portal. The portal will provide credentials.

Errors

We use standard HTTP status codes to show whether an API request succeeded or not. They are usually in the range:

  • 200 to 299 if it succeeded, including code 202 if it was accepted by an API that needs to wait for further action
  • 400 to 499 if it failed because of a client error by your application
  • 500 to 599 if it failed because of an error on our server

Errors specific to each API are shown in the Endpoints section, under Response. See our reference guide for more on errors.


Endpoints

Get current COVID-19 medical exemption status

get /QuestionnaireResponse

Given an NHS number, get the patient's current COVID-19 medical exemption status. Also returns the patient's demographic details, as captured at the point of the exemption decision being made.

Sandbox testing

You can test the following scenarios in our sandbox environment:

Sample outputs are generated using any patient.identifer where the remainder of dividing by 5. (i.e. id % 5 == X)

Scenario Request Response
No Current Exemption patient.identifier = https://fhir.nhs.uk/Id/nhs-number|<X%5==0> HTTP Status 200 with empty bundle in response body
Exempt from Vaccination patient.identifier = https://fhir.nhs.uk/Id/nhs-number|<X%5==1> HTTP Status 200 with exemption data in response body
Exempt from Vaccination and Testing patient.identifier = https://fhir.nhs.uk/Id/nhs-number|<X%5==2> HTTP Status 200 with exemption data in response body
Declined for Vaccination patient.identifier = https://fhir.nhs.uk/Id/nhs-number|<X%5==3> HTTP Status 200 with exemption data in response body
Declined for Vaccination and Testing patient.identifier = https://fhir.nhs.uk/Id/nhs-number|<X%5==4> HTTP Status 200 with exemption data in response body

You can try out the sandbox using the 'Try this API' feature on this page.

Request

Query parameters
Name Description
patient.identifier

String

The patient's NHS number. Expressed as <type>|<value> where <type> must be https://fhir.nhs.uk/Id/nhs-number and <value> must be a valid NHS number.

Pattern: /^https:\\/\\/fhir\.nhs\.uk\\/Id\\/nhs-number\|[0-9]+$/

Example: https://fhir.nhs.uk/Id/nhs-number|9912003888

Required
questionnaire

String

The questionnaire to be consumed

Example: https://fhir.nhs.uk/Questionnaire/COVIDVaccinationMedicalExemption

Optional
Headers
Name Description
Authorization

String

An OAuth 2.0 bearer token, obtained using our NHS login pattern.

Pattern: /^Bearer\ .+$/

Example: Bearer g1112R_ccQ1Ebbb4gtHBP1aaaNM

Optional
X-Correlation-ID

UUID (uuid)

An optional ID which you can use to track transactions across multiple systems. It can take any value, but we recommend avoiding . characters.

Mirrored back in a response header.

Example: 11c46f5f-cdef-4865-94b2-0ee0edcc26da

Optional

Response

HTTP status: 200

The request was valid, and the response contains a current exemption and associated patient details. If there are no exemptions for the given NHS number, the response bundle will be empty.

Headers
Name Description
X-Correlation-Id

String

The X-Correlation-ID from the request header, if supplied, mirrored back.

Example: 11C46F5F-CDEF-4865-94B2-0EE0EDCC26DA

Body

Content type: application/fhir+json

Example

Schema

Name Description
object
resourceType
string
required
Allowed values: Bundle
type
string
required
Allowed values: searchset
entry
array
object
fullUrl
string
resource
object

A structured set of questions and their answers. The questions are ordered and grouped into coherent subsets, corresponding to the structure of the grouping of the questionnaire being responded to.

resourceType
string

This is a QuestionnaireResponse resource

id
string

The logical id of the resource, as used in the URL for the resource. Once assigned, this value never changes.

questionnaire
string

The Questionnaire that defines and organizes the questions for which answers are being provided.

status
string
Allowed values: in-progress, completed, amended, entered-in-error, stopped
subject
object

The subject of the questionnaire response. This could be a patient, organization, practitioner, device, etc. This is who/what the answers apply to, but is not necessarily the source of information.

reference
string
identifier
object
required
system
string
value
string
display
string
required
contained
object

These resources do not have an independent existence apart from the resource that contains them - they cannot be identified independently, and nor can they have their own independent transaction scope.

id
string
required
resourceType
string
required
Allowed values: Patient
birthDate
string
required
item
array
object

A structured set of questions and their answers. The questions are ordered and grouped into coherent subsets, corresponding to the structure of the grouping of the questionnaire being responded to.

linkId
string
required

The item from the Questionnaire that corresponds to this item in the QuestionnaireResponse resource.

answer
array
required

The respondent\u0027s answer(s) to the question.

object

A structured set of questions and their answers. The questions are ordered and grouped into coherent subsets, corresponding to the structure of the grouping of the questionnaire being responded to.

valueDateTime
string

The answer (or one of the answers) provided by the respondent to the question.

Pattern: ^([0-9]([0-9]([0-9][1-9]|[1-9]0)|[1-9]00)|[1-9]000)(-(0[1-9]|1[0-2])(-(0[1-9]|[1-2][0-9]|3[0-1])(T([01][0-9]|2[0-3]):[0-5][0-9]:([0-5][0-9]|60)(\.[0-9]+)?(Z|(\+|-)((0[0-9]|1[0-3]):[0-5][0-9]|14:00)))?)?)?$
valueCoding
object

The value of the input parameter as a basic type.

code
string

A symbol in syntax defined by the system. The symbol may be a predefined code or an expression in a syntax defined by the coding system (e.g. post-coordination).

display
string

A representation of the meaning of the code in the system, following the rules of the system.

HTTP status: 4XX

An error occurred as follows:

HTTP status Error code Description
400 processing Missing or invalid NHS number
400 processing Missing or invalid questionnaire
401 processing Missing or invalid ID token
401 processing Missing or invalid OAuth 2.0 bearer token
401 processing NHS number in request doesn't match NHS number in NHS login account

For details see the diagnostics field.

Body

Content type: application/fhir+json

Example

Schema

Name Description
object

Outcome of an operation that does not result in a resource or bundle being returned, for example an error or an async/batch submission. There are a number of possible error codes that can be returned along with a more detailed description in the diagnostics field.

resourceType
string
required

FHIR Resource Type.

Default: OperationOutcome
issue
array
required

List of issues that have occurred.

Min items: 1
object
severity
string
required

Severity of the error.

Allowed values: fatal, error, warning, information
code
string
required

FHIR error code.

Allowed values: processing
diagnostics
string

Additional diagnostic information about the issue.

Example: Unknown search parameter 'codeing' for resource type 'Immunization'.

Last edited: 11 January 2023 4:55 pm