Skip to main content

COVID-19 Test Results - FHIR API

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

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

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

Details to follow.

Endpoints: Observation

Get COVID-19 test history

get
/Observation
Try this API

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|9912003888 HTTP Status 200 with test results data in response body
No test results found patient.identifier= anything else HTTP Status 200 with empty bundle 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.
Example: https://fhir.nhs.uk/Id/nhs-number|9912003888
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 citizen, 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
{
  "resourceType" : "Bundle",
  "type" : "searchset",
  "total" : 2,
  "entry" : [ {
    "fullUrl" : "https://test-results-api.nhs.uk/FHIR/R4/Observation/ASD32145123",
    "resource" : {
      "resourceType" : "Observation",
      "id" : "ASD32145123",
      "status" : "final",
      "identifier" : [ {
        "system" : "https://fhir.nhs.uk/Id/SpecimenId",
        "value" : "ASD32145123"
      } ],
      "subject" : {
        "reference" : "Patient/9912003888",
        "identifier" : {
          "system" : "https://fhir.nhs.uk/Id/nhs-number",
          "value" : "9912003888"
        }
      },
      "code" : {
        "coding" : [ {
          "system" : "http://snomed.info/sct",
          "code" : "871562009",
          "display" : "Detection of Severe acute respiratory syndrome coronavirus 2 (observable entity)"
        } ]
      },
      "effectiveDateTime" : "2021-04-20T00:00:00+00:00",
      "valueCodeableConcept" : {
        "coding" : [ {
          "system" : "http://snomed.info/sct",
          "code" : "1322791000000100",
          "display" : "SARS-CoV-2 (severe acute respiratory syndrome coronavirus 2) antigen detection result negative"
        } ]
      },
      "device" : {
        "identifier" : {
          "system" : "https://fhir.nhs.uk/Id/Covid19-TestKit",
          "value" : "LFT"
        },
        "display" : "Lateral Flow Test"
      },
      "performer" : [ {
        "type" : "Organization",
        "identifier" : {
          "type" : {
            "coding" : [ {
              "system" : "https://fhir.nhs.uk/CodeSystem/organisation-role",
              "code" : "173",
              "display" : "PATHOLOGY LAB"
            } ]
          },
          "value" : "LFDSelfTest"
        }
      }, {
        "type" : "Organization",
        "identifier" : {
          "type" : {
            "text" : "Testing Centre"
          },
          "value" : "BBC"
        }
      } ],
      "extension" : [ {
        "url" : "https://fhir.nhs.uk/StructureDefinition/Extension-COVID19-TestResult",
        "extension" : [ {
          "url" : "reportOrigin",
          "valueCodeableConcept" : {
            "text" : "LEADER"
          }
        }, {
          "url" : "administrationMethod",
          "valueCodeableConcept" : {
            "text" : "health_care_professional"
          }
        } ]
      } ]
    },
    "search" : {
      "mode" : "match"
    }
  }, {
    "fullUrl" : "https://test-results-api.nhs.uk/FHIR/R4/Observation/ASD3214444",
    "resource" : {
      "resourceType" : "Observation",
      "id" : "ASD3214444",
      "status" : "final",
      "identifier" : [ {
        "system" : "https://fhir.nhs.uk/Id/SpecimenId",
        "value" : "ASD32145127"
      } ],
      "subject" : {
        "reference" : "Patient/9912003888",
        "identifier" : {
          "system" : "https://fhir.nhs.uk/Id/nhs-number",
          "value" : "9912003888"
        }
      },
      "code" : {
        "coding" : [ {
          "system" : "http://snomed.info/sct",
          "code" : "871562009",
          "display" : "Detection of Severe acute respiratory syndrome coronavirus 2 (observable entity)"
        } ]
      },
      "effectiveDateTime" : "2021-04-20T00:00:00+00:00",
      "valueCodeableConcept" : {
        "coding" : [ {
          "system" : "http://snomed.info/sct",
          "code" : "1240581000000104",
          "display" : "SARS-CoV-2 (severe acute respiratory syndrome coronavirus 2) detection result positive"
        } ]
      },
      "device" : {
        "identifier" : {
          "system" : "https://fhir.nhs.uk/Id/Covid19-TestKit",
          "value" : "LFT"
        },
        "display" : "Lateral Flow Test"
      },
      "performer" : [ {
        "type" : "Organization",
        "identifier" : {
          "type" : {
            "coding" : [ {
              "system" : "https://fhir.nhs.uk/CodeSystem/organisation-role",
              "code" : "173",
              "display" : "PATHOLOGY LAB"
            } ]
          },
          "value" : "LFDSelfTest"
        }
      }, {
        "type" : "Organization",
        "identifier" : {
          "type" : {
            "text" : "Testing Centre"
          },
          "value" : "BBC"
        }
      } ],
      "extension" : [ {
        "url" : "https://fhir.nhs.uk/StructureDefinition/Extension-COVID19-TestResult",
        "extension" : [ {
          "url" : "reportOrigin",
          "valueCodeableConcept" : {
            "text" : "LEADER"
          }
        }, {
          "url" : "administrationMethod",
          "valueCodeableConcept" : {
            "text" : "health_care_professional"
          }
        } ]
      } ]
    },
    "search" : {
      "mode" : "match"
    }
  }, {
    "fullUrl" : "https://dev.api.service.nhs.uk/covid-19-test-result/FHIR/R4/Patient/9686368973",
    "resource" : {
      "resourceType" : "Patient",
      "id" : "9686368973",
      "identifier" : [ {
        "extension" : [ {
          "url" : "https://fhir.hl7.org.uk/StructureDefinition/Extension-UKCore-NHSNumberVerificationStatus",
          "valueCodeableConcept" : {
            "coding" : [ {
              "system" : "https://fhir.hl7.org.uk/CodeSystem/UKCore-NHSNumberVerificationStatus",
              "code" : "01",
              "display" : "Number present and verified"
            } ]
          }
        } ],
        "system" : "https://fhir.nhs.uk/Id/nhs-number",
        "value" : "9686368973"
      } ],
      "birthDate" : "1997-12-28"
    },
    "search" : {
      "mode" : "include"
    }
  } ]
}
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/9912003888
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: 9912003888
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
Example: 871555000
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
Example: lampore
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
Example: electiveCare
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
Example: 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: 9912003888
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.