NHS England Immunization API

openapi: 3.2.0
info:
  version: 1.0.0
  title: Immunisation History - FHIR Immunization API
  license:
    name: MIT
  contact:
    name: NHS Digital API Management
    url: https://digital.nhs.uk/developer/help-and-support
    email: api.management@nhs.net
  description: '## Overview

    Use this API to access a patient''s immunisation history.'
servers:
- url: https://sandbox.api.service.nhs.uk/immunisation-history/FHIR/R4
  description: Sandbox environment.
- url: https://int.api.service.nhs.uk/immunisation-history/FHIR/R4
  description: Integration test environment.
- url: https://api.service.nhs.uk/immunisation-history/FHIR/R4
  description: Production environment.
tags:
- name: Immunization
paths:
  /Immunization:
    get:
      summary: Get immunisation history
      operationId: get-immunisation-history
      description: '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\|9000000009` | HTTP Status 200 with immunisation data in response body |

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


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


        ![Run in Postman](https://app.getpostman.com/run-collection/b7dfde415e5726658d09)'
      parameters:
      - name: patient.identifier
        in: query
        description: '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](https://www.datadictionary.nhs.uk/attributes/nhs_number.html).

          '
        required: true
        schema:
          type: string
          example: https://fhir.nhs.uk/Id/nhs-number|9000000009
      - name: procedure-code:below
        deprecated: true
        in: query
        description: 'Parent SNOMED immunisation procedure code.

          For example, `90640007`, which is the parent code for all COVID-19 vaccinations.

          This parameter has been deprecated and will be replaced by the `immunization.target` parameter.

          '
        required: false
        schema:
          type: string
          description: Parent SNOMED code for all COVID-19 vaccinations.
      - name: immunization.target
        in: query
        description: 'Immunization History is segmented into multiple Data Stores, which may target specific procedures, disorders, diseases, infections or organisms.

          '
        schema:
          type: string
          example: COVID19
          enum:
          - COVID19
          - HPV
          - FLU
      - name: date.from
        in: query
        description: 'The earliest date to be included (e.g. 2020-01-01)

          '
        schema:
          type: string
          format: date
          default: '1900-01-01'
      - name: date.to
        in: query
        description: 'The latest date to be included (e.g. 2020-12-31)

          '
        schema:
          type: string
          format: date
          default: '9999-12-31'
      - name: _include
        in: query
        description: 'Specifies other resources to be included in the response along with the immunisations.

          Must be `Immunization:patient`, which will include patient demographic details.

          '
        required: true
        schema:
          type: string
          example: Immunization:patient
      - name: Authorization
        in: header
        description: 'An OAuth 2.0 bearer token, obtained using our [NHS login pattern](https://digital.nhs.uk/developer/guides-and-documentation/security-and-authorisation/user-restricted-restful-apis-nhs-login-separate-authentication-and-authorisation).

          '
        required: true
        schema:
          type: string
          format: ^Bearer\ [[:ascii:]]+$
          example: Bearer g1112R_ccQ1Ebbb4gtHBP1aaaNM
      - name: X-Correlation-ID
        in: header
        required: false
        description: '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.

          '
        schema:
          type: string
          example: 11C46F5F-CDEF-4865-94B2-0EE0EDCC26DA
      - name: Accept
        in: header
        required: false
        description: 'Optional header to select the version of the api. Version number will follow semver.

          '
        schema:
          type: string
          example: version=1.0, version=2.0
      responses:
        '200':
          description: '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:
            X-Correlation-Id:
              $ref: components/schemas/XCorrelationId.yaml
          content:
            application/fhir+json:
              schema:
                $ref: components/schemas/Bundle.yaml
              example:
                $ref: components/examples/Immunization.json
        4XX:
          description: 'An error occurred as follows:


            | HTTP status | Error code                 | Description                                                         |

            | ----------- | -------------------------- | ------------------------------------------------------------------- |

            | 400         | `processing`               | Missing or invalid NHS number                                       |

            | 400         | `processing`               | Missing, invalid or conflicting parent SNOMED code / Target         |

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

            '
          content:
            application/fhir+json:
              schema:
                $ref: components/schemas/OperationOutcome.yaml
              example:
                $ref: components/examples/OperationOutcome.json
      tags:
      - Immunization
x-nhs-api-spec-guid: 1b22efff-7b41-4fa0-9146-dc87686a7b5c