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
- Complete an application through https://portal.developer.nhs.uk/ to the developer environment
- The DDA team will approve access through the portal. The portal will provide credentials.
- 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
- The Direct Data Access team as the API producer will be notified as part of the review team
- The DDA team will contact you to confirm any details needed before permission can be granted
- Complete an application through https://portal.developer.nhs.uk/ to the live environment
- 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
{
"resourceType" : "Bundle",
"type" : "searchset",
"entry" : [ {
"fullUrl" : "QuestionnaireResponse/106218-1.1",
"resource" : {
"resourceType" : "QuestionnaireResponse",
"id" : "106218-1.1",
"questionnaire" : "https://fhir.nhs.uk/Questionnaire/COVIDVaccinationMedicalExemption",
"status" : "completed",
"subject" : {
"reference" : "#p1",
"identifier" : {
"system" : "https://fhir.nhs.uk/Id/nhs-number",
"value" : "6077782459"
},
"display" : "Ivor Fritagelse"
},
"contained" : [ {
"id" : "p1",
"resourceType" : "Patient",
"birthDate" : "1965-02-28"
} ],
"item" : [ {
"linkId" : "exemptionStatus",
"answer" : [ {
"valueCoding" : {
"system" : "https://fhir.nhs.uk/CodeSystem/covid-vaccination-medical-exemption",
"code" : "2",
"display" : "Approved: Exemption from COVID vaccination and testing"
}
} ]
}, {
"linkId" : "exemptionPeriodStart",
"answer" : [ {
"valueDateTime" : "2021-09-29T12:58:01+00:00"
} ]
}, {
"linkId" : "exemptionPeriodEnd",
"answer" : [ {
"valueDateTime" : "2021-11-12T12:59:01+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
|
|
|
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'.
|
