API user guidance

The Immunisation FHIR API performs limited checks related to the patient details and the NHS number provided to the API either in the request or the payload.

The responsibility for accurate identification of patients and the use of NHS numbers belongs with the connecting systems. Any validation performed within the API does not negate that responsibility.

Patient tracing

The connecting system will manage the identification and matching of the patient to an accurate NHS number for use in all interactions with the API. The connecting system may do this in any approved manner for PDS interactions. Connecting systems shall be responsible for taking corrective actions related to any transactions where incorrect patient details have been shared with the API.

Deceased patient records

We recognise some valid use cases for vaccination events related to a deceased patient to be sent and retrieved. Whilst it is expected there is a limited window of time when this should occur, a time limit is not enforced.

The API therefore does not prevent transactions for a patient whose record is flagged as deceased on PDS. It is the responsibility of the connecting system to put controls in place to ensure the API interactions are used appropriately for deceased patient records according to your use cases and any NHS guidance for handling deceased patient records.

Sensitive patient records

This API handles a few data elements such as:

• the location where the vaccination was given (the location elements must be populated normally for information sent to the API for vaccination events)
• the managing organisation for the vaccination
• patient postcode at the time of the vaccination

The search and read interactions will return the location-related content which has been provided, regardless of whether the patient associated with those records is flagged as location data sensitive. The connecting system requesting the records must be responsible for safe handling of this information.

The connecting system shall implement the appropriate access controls according to its assessment of the patient care need being supported (and the associated user access need) against data sensitivity. This is a business process logic for the connecting system to determine and apply in accordance with NHS PDS guidance on sensitive patient record handling.

The connecting system must therefore ensure it checks the patient demographics appropriately, so it is aware of patient warning flags, specifically the sensitive flag (restricted flag in PDS FHIR API) and whether any location-related data in the vaccination event is or is not available to their users.

Merged patient records

Connecting systems should only use the current NHS number for interactions with the API. A vaccination event submitted to the API as a new or updated record will be rejected if the NHS number provided is not the current patient's NHS number at the point the record is received by the API. 

A connecting system shall update its records where it is aware a merge has occurred with a patient record, resulting in a new NHS number being assigned and shall use the new NHS number for all future interaction with the API for that patient. 

The vaccination records held by this service will be updated where an NHS number change occurs as a result of the merging of patient records on PDS. This update may not be applied immediately. This could result in an empty bundle response or a response missing vaccination records when a search interaction occurs.

Connecting systems should inform users of the potential impact of this (along with other reasons why vaccination records may not be available or complete) and ensure mitigations are in place. 

Invalid patient records

Connecting systems will check if the NHS number is current and valid. The API does not accept, create or update interactions for a patient's NHS number which is invalid. An error response will be returned in this circumstance.

If a vaccination event is held against a patient's NHS number which becomes invalid, it will remain associated with the original NHS number.

There is no process for the API record store to transfer records to a new NHS number. It is the responsibility of the connecting system to instigate changes to its records where it's aware a patient has been assigned a new NHS number.  The connecting system shall determine the appropriate action to administer the records locally and with the API. 

Connecting systems should be aware that this is a potential cause for a patient's vaccination history to be incomplete when searched in this API. 

Unknown NHS number

Connecting systems should make every reasonable effort to obtain the correct NHS number for a patient when a vaccination is administered.

You may delay the submission of records to the API for a reasonable period to enable processes to trace a patient to an NHS number. Whilst we require an NHS number wherever possible, the API will accept a vaccination event where an NHS number cannot be obtained for the patient in a timely manner. It is important that, wherever possible, the vaccination event is updated by the connecting system upon any subsequent tracing which obtains the patient's NHS number. 

Patient vaccination events submitted without an NHS number cannot be retrieved by a search as the NHS number is a mandatory search parameter. The connecting system can update, delete or read the vaccination event through the use of the ID returned by the API when the vaccination event is originally submitted to the API.

It is important the connecting system stores the ID provided and can use this in subsequent API transactions in these circumstances, as it may not be possible to obtain the ID through search.

Search verbs

The API search interactions support searching with the GET and PUT verbs and their associated syntax. Connecting systems can use either of these to search for vaccination records. It is expected that most implementations will only use the GET verb and syntax. Onboarding and solution assurance will only require evidence of compliance with the connecting system's selected approach, that is you will not be required to show evidence of an interaction you are not using.

Search parameters

The API supports a limited set of search parameters. Of the standard FHIR search parameters for the immunization resource, only the patient parameter is support and that should only be used with the NHS number as an identifier for the patient.

See the Immunisation FHIR API for full details. The search options may be expanded in the future if suitable use cases are presented and approved.

Custom parameters

In addition to searching by NHS Number, a few custom parameters have been created in accordance with FHIR guidance on nomenclature. These all have a dash prefix. 

Immunization.target serach

This is a mandatory parameter. This requires a code for a vaccine type such as RSV or MMR. These are codes defined by the API, that is they are not from SNOMED CT or NHS data dictionary.

The search supports multiple codes to be included, so you can search for multiple vaccine types in one request. This could be when more than one vaccination is being administered, such as a COVID and flu administration, when you wish to search for vaccination history for both or where you wish to check for vaccination history against a specific disease which may have been administered via different vaccine types. 

If multiple codes are included, and you need to separate the resources response to the respective vaccine type, you should use the SNOMED CT disease codes in the protocolApplied.targetDisease element.

Full details can be found regarding the relationship between the search codes and targetDisease codes in Coding for vaccination disease types.

Date search

This is an optional parameter.

You may choose to limit the payload response to a specific date period or from or to a specific date if you do not require a full history. It is for the connecting system to determine if it wishes to implement support for date-limited searches.

The connecting system will determine how to represent vaccination events in a clinically safe and effective manner. You must adhere to any contractual or national requirements relevant to your use case.

The API requirements do not specify any additional criteria for the connecting system user interface. However, the assurance process will include a review of the representation of vaccination history from search results, and you may be asked to provide justification for any elements missing or unnecessary according to your use case. This may include provision in the clinical safety case / hazard log if there are significant unaddressed concerns.

The API is FHIR r4 based and designed to conform to the UK Core STU3 immunization structure definition. Submitted records are validated to this standard (and in many cases to additional criteria). The resource is stored as received. The API does not FHIR validate the resources in response payloads, so the connecting system will assess for itself the risk / benefit of applying any FHIR structure validation.

Connecting systems should be developed only to the base UK Core definitions. Whilst the API places some additional constraints on vaccination events being submitted, older data may not conform to the same constraints currently applied. Equally, where historical data is required and has been sourced from various systems and then migrated to the API data store, the records are not likely to meet the current constraints (but should still meet the UK Core minimum standard). 

Should there be a need to change the validation levels for vaccination event data in the API, the change will not be considered a breaking change for search responses if the revised version continues to conform to UK Core.

The API search is designed to be responsive to unknown content in the search request. This means that where the request is syntactically correct, but includes unrecognised or unsupported parameters, the API will still respond.

The connecting system can validate this by checking the bundle.link element and validating it against its own request. Anything included in the request, but not present in the returned link has been excluded from the search process.

It is for the connecting system to determine whether to utilise this information according to its use case. In addition, a search bundle may include an operationOutcome with information about the response. An example could be that the operationOutcome informs that some search parameters were not applied due to insufficient permissions. We encourage connecting systems to make use of any operationOutcome resource. 

Whilst we expect a very high percentage of search requests to return a full history to the scope of the data for each vaccine type, we are aware there are a multitude of reasons the vaccination history for a patient may be incomplete at any given time.

Examples include but are not limited to:

• a very recent vaccination event has been supplied in a batch transaction rather than a REST API POST and is not available for up to 48 hours
• a vaccination was administered by a service or system which does not share a vaccination event with our service
• a vaccination event has failed a validation and has not yet been corrected and resubmitted
• a vaccination event has been recorded to an incorrect or out-of-date NHS number or without an NHS number

The connecting system users should follow best practices for their use case with regard to assessing the accuracy of the patient vaccination history provided by the API, such as verification of the relevant history with the patient or a second data source.

The API should not be affected by modifier elements of the immunization resource.

There are two modifier elements.

1. The status element.  This must be populated, but this API does not allow use of `entered-in-error` and `not-done` values, so all records are expected to represent vaccinations administered and correct at that point in time.

2. The isSubpotent element. The API does not allow population of isSubpotent.

Connecting systems should be aware of the implication of these modifiers and the extent to which they are supported and determine how users can be informed of the implications and safe handling of the records.

Allergic reactions or adverse events

This API does not allow content to be provided in the immunization resource relating to details of an allergic reaction or other adverse event as a consequence of vaccine administration. Whilst this information is clearly of high significance in many circumstances, it is outside the scope of this API.

Organisations using this API in circumstances where there is a need to know if the patient has an allergy to the vaccine or has had any other adverse reaction should seek to obtain the information from another source. This may need to be considered in your clinical safety assessment of your solution.

This API only supports the FHIR completed status code. Connecting systems capturing planned vaccinations where the vaccine is not administered, or any other local system records representing a vaccination event which has not been given status=not-donewill not be submitted to the API.

Records which were submitted under earlier versions of the data specification for vaccination events where not given vaccinations were supported are not transferred to the API data store. so are not available to read, update or delete via the API and will not be present in search results from the API.