Skip to main content
Creating a new NHS England: NHS England and NHS Digital merged on 1 February 2023. More about the merger.

FHIR Converter API

Convert FHIR resources from FHIR STU3 to FHIR R4 and vice versa.

This specification is written from an OAS file.

Overview

Use this API to convert resource types MedicationRequest and MedicationStatements from STU3 to FHIR R4 and vice versa.

You can:

  • post either a MedicationRequest or MedicationStatement

You cannot:

  • convert between any other resource types

To use this API:

  1. Send your source payload to this API.
  2. This API converts your source payload to the target version.
  3. You receive the converted payload in the response.

Who can use this API

This API 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. You must do this before you can go live (see ‘Onboarding’ below).


API status and roadmap

This API is in development, meaning:

  • the API is available in our sandbox and integration test environments
  • the API is not yet available for production use
  • we might make breaking changes, but only if we cannot avoid it, and we'll give advance notice

If you have any other queries, please 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 and uses HTTP POST to submit data. It is synchronous - you receive your converted resource in the response body.

It conforms to the FHIR global standard for health care data exchange, specifically to FHIR R4 (v4.0.1), except that it does not support the capabilities interaction.


Network access

This API is available on the internet.

For more details, see Network access for APIs.


Security and authorisation

Application-restricted access

This access mode is application-restricted, meaning we authenticate the calling application but not the end user.

This access mode uses the following security pattern:


Supported FHIR resources and extensions

This service supports conversion from STU3 to R4 and vice versa for following FHIR resources:

  • Bundle
  • MedicationRequest
  • MedicationStatement

For STU3 to R4 conversion, this service can convert various extensions as listed in the version v0.1.0 of the fhir-transform repository. This repository contains the mapping definitions for various UK Core and Care Connect extensions.


Environments and testing

Environment Base URL
Integration test https://int.api.service.nhs.uk/fhir-converter
Production Not yet available

Our integration test environment:

  • is for formal integration testing
  • is for receiving data quality reports of test data

For more details see integration testing with our RESTful APIs.


Errors

We use standard HTTP status codes to show whether an API request succeeded or not. They are usually in the range:

  • 200 to 299 if it succeeded, including code 202 if it was accepted by an API that needs to wait for further action
  • 400 to 499 if it failed because of a client error by your application
  • 500 to 599 if it failed because of an error on our server

Errors specific to each API are shown in the Endpoints section, under Response. See our reference guide for more on errors.


Endpoints

Convert FHIR payload

post /$convert

Overview

Use this endpoint to convert resource types MedicationRequest and MedicationStatements from FHIR STU3 to FHIR R4 and vice versa.

Request

Body
Optional

Content type: application/fhir+json; fhirVersion=3.0

Examples

Schema

Name Description

Content type: application/fhir+xml; fhirVersion=3.0

Examples

Schema

Name Description

Content type: application/fhir+json; fhirVersion=4.0

Examples

Schema

Name Description

Content type: application/fhir+xml; fhirVersion=4.0

Examples

Schema

Name Description

Response

HTTP status: 200

Successful convertion

Body

Content type: application/fhir+json; fhirVersion=3.0

Examples

Content type: application/fhir+xml; fhirVersion=3.0

Examples

Content type: application/fhir+json; fhirVersion=4.0

Examples

Content type: application/fhir+xml; fhirVersion=4.0

Examples

HTTP status: 400

Invalid request

Body

Content type: application/fhir+json; fhirVersion=4.0

Example

Last edited: 16 December 2022 1:55 pm