COVID-19 Test Results - FHIR API
Access a patient’s coronavirus (COVID-19) test results history.
COVID-19 Test History API is on a PRIVATE beta stage. Please contact if you want to be involved.
Use this API to access a patient’s coronavirus (COVID-19) test results history.
- get a patient's COVID-19 test history, based on their NHS number with an optional specific date range
You cannot currently use this API to:
- get details of other types of test
You get the following data:
- COVID-19 test event details
Data availability, timing and quality
All test 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 test event, sometimes sooner.
In a very small number of cases, we are unable to verify the NHS number, and we do not make the test record available at all.
Who can use 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 private beta, meaning:
- it is available for testing use
- it is available for production use after approval and adding to private beta
- we might make breaking changes
If you would like to be involved in our beta programme, contact us.
This API is a platinum service, meaning it is available and supported 24 x 7 x 365.
For more details, see service levels.
This API is RESTful.
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
- array names are singular, for example
entriesfor address lines
- data items that are country-specific and thus not included in the FHIR global base resources are usually wrapped in an
There are libraries and SDKs available to help with FHIR API integration.
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 is application-restricted, meaning we authenticate the calling application but not the end user.
Specifically, it uses the following security pattern:
- the end user must be a patient
- the calling application must strongly authenticate the end user using NHS login
- specifically, the end user must have their identity verified to 'high' (P9) level
- the calling application must pass the user's NHS login identity token in the
NHSD-User-Identityheader when calling the API
- the NHS number in the identity token must match the NHS number for which data is being requested
Environments and testing
|Environment||Base URL||Associated NHS login environment|
||NHS login - Sandpit|
||NHS login - Integration (aos)|
||NHS login - Live (production)|
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:
Our development environment:
- is for early development testing
- includes authorisation using the NHS Sandpit
Available test NHS patients:
- is for formal integration testing
- includes authorisation
Available test NHS patients:
|NHS number||Data profile|
For more details see integration testing with our RESTful APIs.
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.
For further information on onboarding contact firstname.lastname@example.org.
Get COVID-19 test history
Given an NHS number, get the patient's COVID-19 test history.
You can test the following scenarios in our sandbox environment:
|COVID-19 test history found||
||HTTP Status 200 with test results data in response body|
|No test results found||
||HTTP Status 200 with empty bundle in response body|
||HTTP Status 400 Bad Request|
You can try out the sandbox using the 'Try this API' feature on this page.
The patient's NHS number.
The effective date range when the observation was recorded and can be used multiple times as a search parameter.
The SNOMED code related to the observation type. It support a single value or comma seperated values (e.g. 871555000,871553007) List of available codes
Adds Patient resource to the search response.
String (^Bearer\ [[:ascii:]]+$)
An OAuth 2.0 bearer token, obtained using our signed JWT authentication pattern.
Example: Bearer g1112R_ccQ1Ebbb4gtHBP1aaaNM
Open ID Connect ID token for the end user patient, as obtained from NHS login.
Must be a signed JWT in the format
An optional ID which you can use to track transactions across multiple systems. It can take any value, but we recommend avoiding
Mirrored back in a response header.
HTTP status: 200
Valid request that returns all accredited systems found that match the search criteria (which may be 0).
The X-Correlation-ID from the request header, if supplied, mirrored back.
Content type: application/fhir+json
HTTP status: 400
Missing or invalid query parameter(s).
HTTP status: 401
Missing or invalid ID/OAuth toke or NHS number in request doesn't match NHS number in ID token.
HTTP status: 404
Invalid endpoint path.