Skip to main content

COVID-19 Medical Exemptions - FHIR API

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

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

Status

This API is in alpha, meaning:

  • it is available for testing but not yet for production use
  • we might make breaking changes

If you would like to be involved in our beta programme, contact us.

Roadmap

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

If you have any other queries, please contact us.


Technology

This API is RESTful.

It also conforms to the FHIR global standard for health care data exchange. Specifically, it is aligned with FHIR UK Core, which is built on FHIR Release 4.

You don’t 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 offers two access modes: User restricted & Application restricted.

User restricted

Application restricted


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

You need to get your software approved by us before it can go live with this API. We call this onboarding. The onboarding process can sometimes be quite long, so it’s worth planning well ahead.

Details to follow.


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

Headers
Name Description
Authorization

String

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

Pattern: /^Bearer\ .+$/

Example: Bearer g1112R_ccQ1Ebbb4gtHBP1aaaNM

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

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
authored
string
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'.