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
{
"resourceType" : "Bundle",
"entry" : [ {
"resource" : {
"resourceType" : "QuestionnaireResponse",
"id" : "2fa8f1b8-caea-4f3d-9978-c0839da568b2",
"questionnaire" : "https://fhir.nhs.uk/Questionnaire/COVIDVaccinationMedicalExemption",
"status" : "completed",
"subject" : {
"identifier" : [ {
"system" : "https://fhir.nhs.uk/Id/nhs-number",
"value" : "9912003888"
} ],
"display" : "Ivor Fritagelse"
},
"authored" : "2021-08-13T17:15:00+00:00",
"item" : [ {
"linkId" : "exemptionStatus",
"answer" : [ {
"valueCoding" : {
"code" : "2",
"display" : "Approved: Exemption from COVID vaccination and testing"
}
} ]
}, {
"linkId" : "exemptionPeriodStart",
"answer" : [ {
"valueDateTime" : "2021-08-13T17:15:00+00:00"
} ]
}, {
"linkId" : "exemptionPeriodEnd",
"answer" : [ {
"valueDateTime" : "2022-08-13T17:15:00+00:00"
} ]
} ]
}
} ]
}
|
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
{
"resourceType" : "OperationOutcome",
"issue" : [ {
"severity" : "error",
"code" : "processing",
"diagnostics" : "Unknown search parameter 'coding' for resource type 'QuestionnaireResponse'."
} ]
}
|
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
|
Default: OperationOutcome
|
|
issue
array
required
|
List of issues that have occurred. Min items: 1
|
|
object
|
|
|
severity
string
required
|
Allowed values: fatal, error, warning, information
|
|
code
string
required
|
Allowed values: processing
|
|
diagnostics
string
|
Additional diagnostic information about the issue. Example: Unknown search parameter 'codeing' for resource type 'Immunization'.
|