Skip to main content

COVID-19 Test Results - FHIR API

Access a patient’s coronavirus (COVID-19) test results history.

Page content

Warning

COVID-19 Test History API is on a PRIVATE beta stage. Please contact if you want to be involved.

Overview

Use this API to access a patient’s coronavirus (COVID-19) test results history.

You can:

  • 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

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 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.

Service level

This API is a platinum service, meaning it is available and supported 24 x 7 x 365.

For more details, see service levels.

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 /Observation not /observation
  • 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 is application-restricted, meaning we authenticate the calling application but not the end user.

Specifically, it uses the following security pattern:

Note that:

  • 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-Identity header 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
Sandbox https://sandbox.api.service.nhs.uk/covid-19-test-result/FHIR/R4 None
Development https://dev.api.service.nhs.uk/covid-19-test-result/FHIR/R4 NHS login - Sandpit
Integration https://int.api.service.nhs.uk/covid-19-test-result/FHIR/R4 NHS login - Integration (aos)
Production https://api.service.nhs.uk/covid-19-test-result/FHIR/R4 NHS login - Live (production)

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:

Run in Postman

Development testing

Our development environment:

  • is for early development testing
  • includes authorisation using the NHS Sandpit

Available test NHS patients:

NHS number
9686368973
9686368906
9658218873
9658218881

Integration testing

Our integration test environment:

  • is for formal integration testing
  • includes authorisation

Available test NHS patients:

NHS number Data profile
9658477860 profile 2
9437573999 profile 5
9453634980 profile 6

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.

For further information on onboarding contact api.management@nhs.net.

Endpoints

Get COVID-19 test history

get 
/Observation

Given an NHS number, get the patient's COVID-19 test history.

Sandbox testing

You can test the following scenarios in our sandbox environment:

Scenario Request Response
COVID-19 test history found patient.identifier=https://fhir.nhs.uk/Id/nhs-number|9000000009 HTTP Status 200 with test results data in response body
No test results found patient.identifier=https://fhir.nhs.uk/Id/nhs-number|9000000033 HTTP Status 200 with empty bundle in response body
Bad Request patient.identifier= anything else HTTP Status 400 Bad Request

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.

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

Required
date

String

The effective date range when the observation was recorded and can be used multiple times as a search parameter.

Example: ge2010-01-01&date=le2011-12-31

code

String

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

Example: 871553007

_include

String

Adds Patient resource to the search response.

Example: Observation:patient

Headers
Name Description
Authorization

String (^Bearer\ [[:ascii:]]+$)

An OAuth 2.0 bearer token, obtained using our signed JWT authentication pattern.

Example: Bearer g1112R_ccQ1Ebbb4gtHBP1aaaNM

Required
NHSD-User-Identity

String

Open ID Connect ID token for the end user patient, as obtained from NHS login. Must be a signed JWT in the format xxxxx.yyyyy.zzzzz. Must be valid i.e. not expired. Must be for a user who has had their identity verified to 'high' (P9) level.

Example: xxxxx.yyyyy.zzzzz

Required
X-Correlation-ID

String

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

Valid request that returns all accredited systems found that match the search criteria (which may be 0).

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

FHIR Bundle containing the query results - a list of matching COVID-19 test results and optionally associated patients.
resourceType
string
required

FHIR resource type. Always Bundle.

Example: Bundle
type
string
required

Indicates how the bundle is intended to be used. Always searchset.

Example: searchset
total
integer
required

Number of matching COVID-19 test results found.

Example: 2
entry
array
required

List of matching COVID-19 test results and associated patients. If there were no matching tests, this is an empty list.
object
fullUrl
string
required

URI for the Observation or Patient resource.

Example: urn:uuid:edea022a-2d81-11eb-adc1-0242ac120001
resource
required

The Observation or Patient resource.
oneOf
object

Observation result related to the requested patient.
resourceType
string
required

FHIR resource type. Always Observation.

Example: Observation
id
string

FHIR resource id.

Example: ASD32145123
status
string

COVID-19 test status. Always final.

Example: final
identifier
array
required

Unique identifier for this COVID-19 test result record, as generated by the source system.

Max items: 1
Min items: 1
object
system
string
required

URI of the namespace of this identifier. Always https://fhir.nhs.uk/Id/SpecimenId.

Example: https://fhir.nhs.uk/Id/SpecimenId
value
string
required

Identifier value within system.

Example: ASD32145123
subject
object

The patient who took the COVID-19 test.
reference
string
required

URI for the associated Patient resource in the bundle.

Example: Patient/9000000009
type
string

Type of resource this reference refers to. Always Patient.

Example: Patient
identifier
object
required

Business identifier for linked Patient. Always an NHS number.
system
string
required

URI of coding system used to identify linked patient.

Example: https://fhir.nhs.uk/Id/nhs-number
value
string
required

Value in coding system representing linked patient.

Example: 9000000009
category
array

The category of test result. Indicates Pillar of the data only

Max items: 1
Min items: 1
object
system
string

Coding system used to indicate Pillar1 data

Example: https://fhir.nhs.uk/CodeSystem/covid-test-pillar
code
string

Code indicating Pillar1 data.

Allowed values: pillar-1, pillar-2
display
string

Description indicating Pillar1 data.

Allowed values: pillar 1, pillar 2
code
object

The category of test result. Describes COVID-19 detection method.
coding
array
required

Wrapper for the test result detection method.

Max items: 1
Min items: 1
object
system
string
required

Coding system used to describe COVID-19 detection method. Always SNOMED.

Example: http://snomed.info/sct
code
string
required

Code for the COVID-19 detection method.

Allowed values: 871555000, 871552002, 871553007
display
string
required

Description of the COVID-19 detection method.

Example: Detection of ribonucleic acid of Severe acute respiratory syndrome coronavirus 2
effectiveDateTime
string

Date and time of the COVID-19 test.

Example: 2021-04-20T00:00:00+00:00
valueCodeableConcept
object

The COVID-19 test result for the specimen analysed.
coding
array
required

Wrapper for the test result.

Max items: 1
Min items: 1
object
system
string
required

Coding system used to describe COVID-19 test result. Always SNOMED.

Example: http://snomed.info/sct
code
string
required

Code for the COVID-19 test result.

Example: 1322791000000100
display
string
required

Description of the COVID-19 test result.

Example: SARS-CoV-2 (severe acute respiratory syndrome coronavirus 2) antigen detection result negative
device
object

The type of test kit used to take the COVID-19 test.
identifier
object
required

Test kit identifier.
system
string
required

Coding system used for the test kit identifier. Always https://fhir.nhs.uk/Id/Covid19-TestKit.

Example: https://fhir.nhs.uk/Id/Covid19-TestKit
value
string
required

Test kit code.

Allowed values: blank (i.e. empty), lampore, rnalamp, directrtlamp, lft, ePCR, rtPCR, elisa
display
string
required

Decsription of the test kit.

Example: Lateral Flow Test
performer
array

Information where the test was taken (Test Centre) and where it was analysed (e.g. a laboratory).

Max items: 2
Min items: 1
oneOf
object

Laboratory code
type
string
required

Always Organization.

Example: Organization
identifier
object
required
type
object
required
coding
array
required
Max items: 1
Min items: 1
object
system
string
required

Coding system used to describe laboratory type. Always https://fhir.nhs.uk/CodeSystem/organisation-role.

Example: https://fhir.nhs.uk/CodeSystem/organisation-role
code
string
required

Code for the laboratory type within system. Always 173.

Example: 173
display
string
required

Always PATHOLOGY LAB.

Example: PATHOLOGY LAB
value
string
required

Unique identifier of the pathology lab.

Example: MK
object

Test Centre identifier.
type
string
required

Always Organization.

Example: Organization
identifier
object
required
type
object
required
text
string
required

Always Testing Centre

Example: Testing Centre
value
string
required

Unique identifier of the Testing Centre.

Example: BBC
extension
array

COVID-19 test results extensions to cover elements not defined in standard FHIR.

Max items: 1
Min items: 1
object
url
string
required

URI for the type of extension. Always https://fhir.nhs.uk/StructureDefinition/Extension-COVID19-TestResult.

Example: https://fhir.nhs.uk/StructureDefinition/Extension-COVID19-TestResult
extension
array
required
Max items: 2
Min items: 1
oneOf
object

Source of record creation.
url
string
required

Always reportOrigin
valueCodeableConcept
object
required
text
string
required

Unique indentifier of the source.

Allowed values: admin, bulk, electiveCare, home, lite, liteSelf, user, assistedExistingBarcode
object

Used to convey how the test was administered.
url
string
required

Always administrationMethod.
valueCodeableConcept
object
required
text
string
required

Unique indentifier of the admin method.

Allowed values: self, health_care_professional
object

Demographic information about the patient whose tests are retrieved.
resourceType
string
required

FHIR resource type. Always Patient.

Example: Patient
identifier
array
required

Unique identifier for this patient. Always an NHS number.

Min items: 1
object
system
string
required

Coding system used to identify patients.

Example: https://fhir.nhs.uk/Id/nhs-number
value
string
required

Code identifying the patient.

Example: 9000000009
birthDate
string
required

Patient's date of birth.

Example: 1965-02-28
search
object
required

Search-related information for the Observation or Patient resource.
mode
string
required

Indicates why this resource is in the result set. For Observation resources this is always match and for Patient resources it is always include.

Allowed values: match, include
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.