Skip to main content

Immunisation History - FHIR API

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

Overview

Use this API to access a patient’s immunisation history.

You can:

  • get a patient's coronavirus (COVID-19) immunisation history, based on their NHS number

You cannot currently use this API to:

  • get details of other types of immunisation
  • get the immunisation history for a specific date range

You get the following data:

  • immunisation event details
  • patient demographic details, as captured at the point of immunisation

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 availability, timing and quality

All immunisation 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 immunisation event, 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 immunisation 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 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 /Immunization not /immunisations
  • 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 user-restricted, meaning an end user must be present and authenticated.

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

Environments and testing

Environment Base URL
Sandbox https://sandbox.api.service.nhs.uk/immunisation-history/FHIR/R4/
Integration test https://int.api.service.nhs.uk/immunisation-history/FHIR/R4/
Production Not yet available

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

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 immunisation history

get
/Immunization

Given an NHS number, get the patient's immunisation history. Also returns the patient's demographic details, as captured at the point of immunisation.

Sandbox testing

You can test the following scenarios in our sandbox environment:

Scenario Request Response
Immunisation history found patient.identifier=https://fhir.nhs.uk/Id/nhs-number|9912003888 HTTP Status 200 with immunisation data in response body
No immunisations 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.

Alternatively, you can try out the sandbox using our Postman collection:

Run in Postman

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
procedure-code:below
String
Parent SNOMED immunisation procedure code. For example, 90640007, which is the parent code for all COVID-19 vaccinations.
Example: 90640007
Required
_include
String
Specifies other resources to be included in the response along with the immunisations. Must be Immunization:patient, which will include patient demographic details.
Example: Immunization:patient
Required
Headers
Name Description
Authorization
String (^Bearer\ [[:ascii:]]+$)
An OAuth 2.0 bearer token, obtained using our NHS login pattern.
Example: Bearer g1112R_ccQ1Ebbb4gtHBP1aaaNM
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
The request was valid, and the response contains immunisation history and associated patient details. If there are no immunisations 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",
  "total" : 2,
  "entry" : [ {
    "fullUrl" : "urn:uuid:edea022a-2d81-11eb-adc1-0242ac120001",
    "resource" : {
      "resourceType" : "Immunization",
      "extension" : [ {
        "url" : "https://fhir.hl7.org.uk/StructureDefinition/Extension-UKCore-VaccinationProcedure",
        "valueCodeableConcept" : {
          "coding" : [ {
            "system" : "http://snomed.info/sct",
            "code" : "1324681000000101",
            "display" : "Administration of first dose of severe acute respiratory syndrome coronavirus 2 vaccine (procedure)"
          } ]
        }
      } ],
      "identifier" : [ {
        "use" : "secondary",
        "system" : "https://supplierABC/identifiers/vacc",
        "value" : "1324761000000100"
      } ],
      "status" : "completed",
      "vaccineCode" : {
        "coding" : [ {
          "system" : "http://snomed.info/sct",
          "code" : "39114911000001105",
          "display" : "COVID-19 Vaccine AstraZeneca (ChAdOx1 S [recombinant]) 5x10,000,000,000 viral particles/0.5ml dose solution for injection multidose vials (AstraZeneca UK Ltd) (product)"
        } ]
      },
      "patient" : {
        "reference" : "urn:uuid:edea022a-2d81-11eb-adc1-0242ac120002",
        "type" : "Patient",
        "identifier" : {
          "system" : "https://fhir.nhs.uk/Id/nhs-number",
          "value" : "9912003888"
        }
      },
      "occurrenceDateTime" : "2020-12-23T13:00:08.476000+00:00",
      "recorded" : "2020-12-23",
      "primarySource" : true,
      "manufacturer" : {
        "display" : "AstraZeneca Ltd"
      },
      "lotNumber" : "R04X",
      "expirationDate" : "2021-04-29",
      "route" : {
        "coding" : [ {
          "system" : "http://snomed.info/sct",
          "code" : "78421000",
          "display" : "Intramuscular route (qualifier value)"
        } ]
      },
      "doseQuantity" : {
        "value" : 0.3,
        "unit" : "mL",
        "system" : "http://snomed.info/sct",
        "code" : "258773002"
      },
      "performer" : [ {
        "actor" : {
          "type" : "Organization",
          "identifier" : {
            "system" : "https://fhir.nhs.uk/Id/ods-organization-code",
            "value" : "RX809"
          }
        }
      } ],
      "reasonCode" : [ {
        "coding" : [ {
          "system" : "http://snomed.info/sct",
          "code" : "443684005",
          "display" : "Disease outbreak (event)"
        } ]
      } ],
      "protocolApplied" : [ {
        "doseNumberPositiveInt" : 1
      } ]
    },
    "search" : {
      "mode" : "match"
    }
  }, {
    "fullUrl" : "urn:uuid:edea022a-2d81-11eb-adc1-0242ac120000",
    "resource" : {
      "resourceType" : "Immunization",
      "extension" : [ {
        "url" : "https://fhir.hl7.org.uk/StructureDefinition/Extension-UKCore-VaccinationProcedure",
        "valueCodeableConcept" : {
          "coding" : [ {
            "system" : "http://snomed.info/sct",
            "code" : "1324691000000104",
            "display" : "Administration of second dose of severe acute respiratory syndrome coronavirus 2 vaccine (procedure)"
          } ]
        }
      } ],
      "identifier" : [ {
        "use" : "secondary",
        "system" : "https://supplierABC/identifiers/vacc",
        "value" : "1324761000000102"
      } ],
      "status" : "completed",
      "vaccineCode" : {
        "coding" : [ {
          "system" : "http://snomed.info/sct",
          "code" : "39114911000001105",
          "display" : "COVID-19 Vaccine AstraZeneca (ChAdOx1 S [recombinant]) 5x10,000,000,000 viral particles/0.5ml dose solution for injection multidose vials (AstraZeneca UK Ltd) (product)"
        } ]
      },
      "patient" : {
        "reference" : "urn:uuid:edea022a-2d81-11eb-adc1-0242ac120002",
        "type" : "Patient",
        "identifier" : {
          "system" : "https://fhir.nhs.uk/Id/nhs-number",
          "value" : "9912003888"
        }
      },
      "occurrenceDateTime" : "2021-02-23T13:00:08.476000+00:00",
      "recorded" : "2021-02-23",
      "primarySource" : false,
      "reportOrigin" : {
        "text" : "RR8 - LEEDS TEACHING HOSPITALS NHS TRUST"
      },
      "manufacturer" : {
        "display" : "AstraZeneca Ltd"
      },
      "lotNumber" : "A04Z",
      "expirationDate" : "2021-06-29",
      "route" : {
        "coding" : [ {
          "system" : "http://snomed.info/sct",
          "code" : "78421000",
          "display" : "Intramuscular route (qualifier value)"
        } ]
      },
      "doseQuantity" : {
        "value" : 0.3,
        "unit" : "mL",
        "system" : "http://snomed.info/sct",
        "code" : "258773002"
      },
      "performer" : [ {
        "actor" : {
          "type" : "Organization",
          "identifier" : {
            "system" : "https://fhir.nhs.uk/Id/ods-organization-code",
            "value" : "RX809"
          }
        }
      } ],
      "reasonCode" : [ {
        "coding" : [ {
          "system" : "http://snomed.info/sct",
          "code" : "443684005",
          "display" : "Disease outbreak (event)"
        } ]
      } ],
      "protocolApplied" : [ {
        "doseNumberPositiveInt" : 2
      } ]
    },
    "search" : {
      "mode" : "match"
    }
  }, {
    "fullUrl" : "urn:uuid:edea022a-2d81-11eb-adc1-0242ac120002",
    "resource" : {
      "resourceType" : "Patient",
      "identifier" : [ {
        "system" : "https://fhir.nhs.uk/Id/nhs-number",
        "value" : "9912003888"
      } ],
      "birthDate" : "1965-02-28"
    },
    "search" : {
      "mode" : "include"
    }
  } ]
}
Schema
Name Description
object
FHIR Bundle containing the query results - a list of matching immunisations and 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 immunisations found.
Example: 2
entry
array
required
List of matching immunisations and associated patients. If there were no matching immunisations, this is an empty list.
object
fullUrl
string
required
URI for the Immunization or Patient resource.
Example: urn:uuid:edea022a-2d81-11eb-adc1-0242ac120001
resource
required
The Immunization or Patient resource.
oneOf
object
A matching immunisation, formatted as a FHIR Immunization resource.
resourceType
string
required
FHIR resource type. Always Immunization.
Example: Immunization
extension
array
required
FHIR extension wrapper for the vaccination procedure performed. Always contains exactly one object.
Max items: 1
Min items: 1
object
url
string
required
URI for the type of extension - in this case a vaccination procedure.
Example: https://fhir.hl7.org.uk/StructureDefinition/Extension-UKCore-VaccinationProcedure
valueCodeableConcept
object
required
Wrapper for the vaccination procedure details.
coding
array
required
Wrapper for the vaccination procedure details.
object
system
string
required
Coding system used for the vaccination procedure. Always SNOMED.
Example: http://snomed.info/sct
code
string
required
SNOMED code for the vaccination procedure.
Example: 1324681000000101
display
string
required
Description of the vaccination procedure.
Example: Administration of first dose of severe acute respiratory syndrome coronavirus 2 vaccine (procedure)
identifier
array
required
Unique identifier for this immunisation record, as generated by the source system.
Max items: 1
Min items: 1
object
use
string
required
Identifier use as defined by https://www.hl7.org/fhir/valueset-identifier-use.html.
Allowed values: usual, official, temp, secondary, old
Example: secondary
system
string
required
URI of the namespace of this identifier.
Example: https://supplierABC/identifiers/vacc
value
string
required
Identifier value within system.
Example: 1324761000000100
status
string
required
Status of the immunisation event. This is not an indication of patient immunity, only whether the immunisation was completed or not. Currently we only return details of completed immunisations.
Allowed values: completed
Example: completed
vaccineCode
object
required
Vaccine product administered.
coding
array
required
Wrapper for the vaccine product details.
Max items: 1
Min items: 1
object
system
string
required
Coding system for type of administered vaccine. Always SNOMED.
Example: http://snomed.info/sct
code
string
required
SNOMED code for the vaccine product.
Example: 39114911000001105
display
string
required
Description of the vaccine product.
Example: COVID-19 Vaccine AstraZeneca (ChAdOx1 S [recombinant]) 5x10,000,000,000 viral particles/0.5ml dose solution for injection multidose vials (AstraZeneca UK Ltd) (product)
patient
object
required
The patient who was immunised.
reference
string
required
URI for the associated Patient resource in the bundle.
Example: urn:uuid:edea022a-2d81-11eb-adc1-0242ac120002
type
string
required
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
occurrenceDateTime
string
required
Date and time of immunisation.
Example: 2020-12-23T13:00:08.476000+00:00
recorded
string
The date the occurrence of the immunization was first captured in the record - potentially significantly after the occurrence of the event.
Example: 2020-12-23
primarySource
boolean
required
An indication that the content of the record is based on information from the person who administered the vaccine. This reflects the context under which the data was originally recorded.
Example: true
reportOrigin
object
Origin of the vaccination report, if not from the primary source. Only present if primarySource=false.
text
string
required
Text description of the origin of the vaccination report.
Example: RR8 - LEEDS TEACHING HOSPITALS NHS TRUST
manufacturer
object
Vaccine manufacturer details.
display
string
required
Decsription of the vaccine manufacturer.
Example: AstraZeneca Ltd
lotNumber
string
Lot number of the vaccine product. Present if and only if status=completed.
Example: R04X
expirationDate
string
Date vaccine batch expires.
Example: 2021-04-29
route
object
The path by which the vaccine product is taken into the body.
coding
array
required
Wrapper for the vaccination route details.
Min items: 1
object
system
string
required
Coding system used to describe vaccination route. Always SNOMED.
Example: http://snomed.info/sct
code
string
required
Code for the vaccination route.
Example: 78421000
display
string
required
Description of the vaccination route.
Example: Intramuscular route (qualifier value)
doseQuantity
object
The quantity of vaccine product that was administered.
value
integer
required
Number of units administered.
Example: 1
unit
string
required
Description of unit.
Example: pre-filled disposable injection
system
string
required
System that defines coded unit form.
Example: http://snomed.info/sct
code
string
required
Code describing the unit.
Example: 3318611000001103
performer
array
required
Details of the organisation that performed the immunisation.
Max items: 1
Min items: 1
object
actor
object
required
Organisation that performed the immunisation.
type
string
required
Type of actor. Always Organisation.
Example: Organisation
identifier
object
required
Organisation identifier.
system
string
required
Coding system used for the organisation identifier. Always https://fhir.nhs.uk/Id/ods-organization-code.
Example: https://fhir.nhs.uk/Id/ods-organization-code
value
string
required
Organisation's ODS code.
Example: RX809
reasonCode
array
Reasons why the vaccine was administered.
Min items: 1
object
coding
array
required
Wrapper for the reason code details.
Min items: 1
object
system
string
required
Coding system used to describe the reason for administration of vaccine. Always SNOMED.
Example: http://snomed.info/sct
code
string
required
SNOMED code for the vaccination reason.
Example: 443684005
display
string
required
Description of the vaccination reason.
Example: Disease outbreak (event)
protocolApplied
array
The protocol (set of recommendations) being followed by the provider who administered the dose. Present only if it contains any elements.
Min items: 1
object
doseNumberPositiveInt
integer
required
Dose number within a series of doses.
Example: 1
object
Demographic information about the patient receiving an immunisation.
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 Immunization or Patient resource.
mode
string
required
Indicates why this resource is in the result set. For Immunization resources this is always match and for Patient resources it is always include.
Allowed values: match, include
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 parent SNOMED code
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 'codeing' for resource type 'Immunization'."
  } ]
}
Schema
Name Description
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
FHIR Resource Type.
Default: OperationOutcome
issue
array
required
List of issues that have occurred.
Min items: 1
object
severity
string
required
Severity of the error.
Allowed values: fatal, error, warning, information
Example: error
code
string
required
FHIR error code.
Allowed values: processing
Example: invalid
diagnostics
string
Additional diagnostic information about the issue.
Example: Unknown search parameter 'codeing' for resource type 'Immunization'.