Skip to main content

Booking and Referral - FHIR API

Send booking and referral information between NHS service providers using our Booking and Referral FHIR API.

Overview

Use this API to send booking and referral information between NHS service providers.

You can:

  • Get a specific booking
  • Get bookings for a patient
  • Process a message
  • Get message definition
  • Get capability statement
  • Get a specific referral
  • Get referral/s for a patient
  • Get slots

The following describes the end-to-end process:

  1. Send a request from your sender application to this API, along with a service identifier header.
  2. This API redirects the request to the service associated with the service identifier header.
  3. The target backend handles the request and sends a response back to this API.
  4. This API returns the response to your sender application.

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.


API status and roadmap

This API is in alpha, meaning:

  • it is available for testing in integration environment
  • we expect to make breaking changes based on developer feedback

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

The API is RESTful.

This API uses HTTP POST to submit data.

The data payload 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, or FHIR GP Connect, which is built on FHIR STU3.


Network access

This API is available on the internet.

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.

You can use this access mode as follows:

  • unattended (end user not present)

To use this access mode, use the following security pattern:


Environments and testing

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

Our integration test environment:

  • is for formal integration testing

For more details see integration testing with our RESTful APIs.


Onboarding

Details to follow.


Endpoints: Booking

Get a specific booking

get
/Appointment/{id}

Get a specific booking

Request

Path parameters
Name Description
id

UUID (uuid)

The identifier of the registry object.

Example: c3f6145e-1a26-4345-b3f2-dccbcba62049

Required
Headers
Name Description
X-Request-ID

UUID (uuid)

The X-Request-ID from the request header, if supplied, mirrored back.

Example: c1ab3fba-6bae-4ba4-b257-5a87c44d4a91

Required
X-Correlation-ID

UUID (uuid)

The X-Correlation-ID from the request header, if supplied, mirrored back.

Example: 9562466f-c982-4bd5-bb0e-255e9f5e6689

Required
NHSD-Target-Identifier

Object

The identifier of the Target system

Required
NHSD-End-User-Organisation

Object

The identifer of the Sending Organisation (to be Base64 encoded).

Required
NHSD-Requesting-Practitioner

Object

The identifer of the Sending System User (to be Base64 encoded).

NHSD-Requesting-Person

Object

The identifer of the Sending Person (to be Base64 encoded).

NHSD-Requesting-Software

Object

The identifer of the Sending System (to be Base64 encoded).

Response

HTTP status: 200

Success

Headers
Name Description
X-Correlation-Id

UUID (uuid)

The X-Correlation-ID from the request header, if supplied, mirrored back.

Example: 9562466f-c982-4bd5-bb0e-255e9f5e6689

X-Request-Id

UUID (uuid)

The X-Request-ID from the request header, if supplied, mirrored back.

Example: c1ab3fba-6bae-4ba4-b257-5a87c44d4a91

Body

Content type: application/fhir+json

Example

Schema

Name Description
object
resourceType
string
Example: Appointment
meta
object
profile
array
string
Example: https://fhir.nhs.uk/StructureDefinition/BARSAppointment

Content type: application/fhir+xml

Schema

Name Description
object
resourceType
string
Example: Appointment
meta
object
profile
array
string
Example: https://fhir.nhs.uk/StructureDefinition/BARSAppointment
HTTP status: 4XX

An error occurred as follows: | HTTP status | Error code | Description | | ----------- | -------------------------- | --------------------------------------------- | | 400 | SEND_BAD_REQUEST | The API was unable to process the request. | | 400 | REC_BAD_REQUEST | The Receiver has responded stating the message was malformed. | | 401 | SEND_UNAUTHORIZED | The API deemed you unauthorized to make this request. | | 401 | REC_UNAUTHORIZED | The receiver deemed you unauthorized to make request. | | 403 | SEND_FORBIDDEN | Missing or Expired Token. | | 404 | PROXY_NOT_FOUND | No related people exist for given NHS number. | | 404 | REC_NOT_FOUND | Patient record for given NHS number has been invalidated and not superseded by another NHS number. | | 405 | SEND_METHOD_NOT_ALLOWED | HTTP Verb is not correct for this scenario.| | 405 | REC_METHOD_NOT_ALLOWED | Receiver does not allow this.| | 405 | PROXY_METHOD_NOT_ALLOWED | Proxy does not allow this.| | 406 | SEND_NOT_ACCEPTABLE | Senders message had an incorrect content type defined for a response.| | 408 | REC_TIMEOUT | The downstream domain processing has not completed within the configured timeout period. | | 409 | SEND_CONFLICT | | | 409 | REC_CONFLICT | | | 409 | PROXY_CONFLICT | | | 422 | SEND_UNPROCESSABLE_ENTITY | Message was not malformed but deemed unprocessable. | | 422 | REC_UNPROCESSABLE_ENTITY | Message was not malformed but deemed unprocessable. |
| 422 | PROXY_UNPROCESSABLE_ENTITY | Message was not malformed but deemed unprocessable. |
| 429 | SEND_TOO_MANY_REQUESTS | The user has sent too many requests in a given amount of time| | 429 | REC_TOO_MANY_REQUESTS | The user has sent too many requests in a given amount of time|

Headers
Name Description
X-Correlation-Id

UUID (uuid)

The X-Correlation-ID from the request header, if supplied, mirrored back.

Example: 9562466f-c982-4bd5-bb0e-255e9f5e6689

X-Request-Id

UUID (uuid)

The X-Request-ID from the request header, if supplied, mirrored back.

Example: c1ab3fba-6bae-4ba4-b257-5a87c44d4a91

Body

Content type: application/fhir+json

Example

Schema

Name Description
object
resourceType
string
Example: OperationalOutcome
meta
object
profile
array
string
Example: https://fhir.nhs.uk/StructureDefinition/BARSOperationalOutcome
HTTP status: 5XX

An error occurred as follows: | HTTP status | Error code | Description | | ----------- | -------------------------- | --------------------------------------------- | | 500 | REC_SERVER_ERROR | The receiver server has encountered an Error processing the request. | | 500 | PROXY_SERVER_ERROR | Proxy Error. | | 501 | SEND_NOT_IMPLEMENTED | The Request was not recognized. | | 501 | REC_NOT_IMPLEMENTED | The Receiver did not recognize the request. | | 501 | PROXY_NOT_IMPLEMENTED | The Proxy did not recognize the request. | | 503 | REC_UNAVAILABLE | The Receiver was unavailable to service the request.| | 503 | PROXY_UNAVAILABLE | The Proxy was unavailable to service the request. |

Headers
Name Description
X-Correlation-Id

UUID (uuid)

The X-Correlation-ID from the request header, if supplied, mirrored back.

Example: 9562466f-c982-4bd5-bb0e-255e9f5e6689

X-Request-Id

UUID (uuid)

The X-Request-ID from the request header, if supplied, mirrored back.

Example: c1ab3fba-6bae-4ba4-b257-5a87c44d4a91

Body

Content type: application/fhir+json

Example

Schema

Name Description
object
resourceType
string
Example: OperationalOutcome
meta
object
profile
array
string
Example: https://fhir.nhs.uk/StructureDefinition/BARSOperationalOutcome

Get bookings for a patient

get
/Appointment

Get Bookings for a patient

Request

Query parameters
Name Description
patientIdentifier

String

The identifier of a patient.

Example: 485 777 3456

Required
Headers
Name Description
X-Request-ID

UUID (uuid)

The X-Request-ID from the request header, if supplied, mirrored back.

Example: c1ab3fba-6bae-4ba4-b257-5a87c44d4a91

Required
X-Correlation-ID

UUID (uuid)

The X-Correlation-ID from the request header, if supplied, mirrored back.

Example: 9562466f-c982-4bd5-bb0e-255e9f5e6689

Required
NHSD-Target-Identifier

Object

The identifier of the Target system

Required
NHSD-End-User-Organisation

Object

The identifer of the Sending Organisation (to be Base64 encoded).

Required
NHSD-Requesting-Practitioner

Object

The identifer of the Sending System User (to be Base64 encoded).

NHSD-Requesting-Person

Object

The identifer of the Sending Person (to be Base64 encoded).

NHSD-Requesting-Software

Object

The identifer of the Sending System (to be Base64 encoded).

Response

HTTP status: 200

Success

Headers
Name Description
X-Correlation-Id

UUID (uuid)

The X-Correlation-ID from the request header, if supplied, mirrored back.

Example: 9562466f-c982-4bd5-bb0e-255e9f5e6689

X-Request-Id

UUID (uuid)

The X-Request-ID from the request header, if supplied, mirrored back.

Example: c1ab3fba-6bae-4ba4-b257-5a87c44d4a91

Body

Content type: application/fhir+json

Example

Schema

Name Description
object
resourceType
string
Example: Bundle
meta
object
profile
array
string
Example: https://fhir.nhs.uk/StructureDefinition/BARSBundle
type
string
Example: searchset

Content type: application/fhir+xml

Schema

Name Description
object
resourceType
string
Example: Bundle
meta
object
profile
array
string
Example: https://fhir.nhs.uk/StructureDefinition/BARSBundle
type
string
Example: searchset
HTTP status: 4XX

An error occurred as follows: | HTTP status | Error code | Description | | ----------- | -------------------------- | --------------------------------------------- | | 400 | SEND_BAD_REQUEST | The API was unable to process the request. | | 400 | REC_BAD_REQUEST | The Receiver has responded stating the message was malformed. | | 401 | SEND_UNAUTHORIZED | The API deemed you unauthorized to make this request. | | 401 | REC_UNAUTHORIZED | The receiver deemed you unauthorized to make request. | | 403 | SEND_FORBIDDEN | Missing or Expired Token. | | 404 | PROXY_NOT_FOUND | No related people exist for given NHS number. | | 404 | REC_NOT_FOUND | Patient record for given NHS number has been invalidated and not superseded by another NHS number. | | 405 | SEND_METHOD_NOT_ALLOWED | HTTP Verb is not correct for this scenario.| | 405 | REC_METHOD_NOT_ALLOWED | Receiver does not allow this.| | 405 | PROXY_METHOD_NOT_ALLOWED | Proxy does not allow this.| | 406 | SEND_NOT_ACCEPTABLE | Senders message had an incorrect content type defined for a response.| | 408 | REC_TIMEOUT | The downstream domain processing has not completed within the configured timeout period. | | 409 | SEND_CONFLICT | | | 409 | REC_CONFLICT | | | 409 | PROXY_CONFLICT | | | 422 | SEND_UNPROCESSABLE_ENTITY | Message was not malformed but deemed unprocessable. | | 422 | REC_UNPROCESSABLE_ENTITY | Message was not malformed but deemed unprocessable. |
| 422 | PROXY_UNPROCESSABLE_ENTITY | Message was not malformed but deemed unprocessable. |
| 429 | SEND_TOO_MANY_REQUESTS | The user has sent too many requests in a given amount of time| | 429 | REC_TOO_MANY_REQUESTS | The user has sent too many requests in a given amount of time|

Headers
Name Description
X-Correlation-Id

UUID (uuid)

The X-Correlation-ID from the request header, if supplied, mirrored back.

Example: 9562466f-c982-4bd5-bb0e-255e9f5e6689

X-Request-Id

UUID (uuid)

The X-Request-ID from the request header, if supplied, mirrored back.

Example: c1ab3fba-6bae-4ba4-b257-5a87c44d4a91

Body

Content type: application/fhir+json

Example

Schema

Name Description
object
resourceType
string
Example: OperationalOutcome
meta
object
profile
array
string
Example: https://fhir.nhs.uk/StructureDefinition/BARSOperationalOutcome
HTTP status: 5XX

An error occurred as follows: | HTTP status | Error code | Description | | ----------- | -------------------------- | --------------------------------------------- | | 500 | REC_SERVER_ERROR | The receiver server has encountered an Error processing the request. | | 500 | PROXY_SERVER_ERROR | Proxy Error. | | 501 | SEND_NOT_IMPLEMENTED | The Request was not recognized. | | 501 | REC_NOT_IMPLEMENTED | The Receiver did not recognize the request. | | 501 | PROXY_NOT_IMPLEMENTED | The Proxy did not recognize the request. | | 503 | REC_UNAVAILABLE | The Receiver was unavailable to service the request.| | 503 | PROXY_UNAVAILABLE | The Proxy was unavailable to service the request. |

Headers
Name Description
X-Correlation-Id

UUID (uuid)

The X-Correlation-ID from the request header, if supplied, mirrored back.

Example: 9562466f-c982-4bd5-bb0e-255e9f5e6689

X-Request-Id

UUID (uuid)

The X-Request-ID from the request header, if supplied, mirrored back.

Example: c1ab3fba-6bae-4ba4-b257-5a87c44d4a91

Body

Content type: application/fhir+json

Example

Schema

Name Description
object
resourceType
string
Example: OperationalOutcome
meta
object
profile
array
string
Example: https://fhir.nhs.uk/StructureDefinition/BARSOperationalOutcome

Endpoints: Message

Process a message

post
/$process-message

Process a message

Request

Headers
Name Description
NHSD-Target-Identifier

Object

The identifier of the Target system

Required
X-Request-ID

UUID (uuid)

The X-Request-ID from the request header, if supplied, mirrored back.

Example: c1ab3fba-6bae-4ba4-b257-5a87c44d4a91

Required
X-Correlation-ID

UUID (uuid)

The X-Correlation-ID from the request header, if supplied, mirrored back.

Example: 9562466f-c982-4bd5-bb0e-255e9f5e6689

Required
NHSD-End-User-Organisation

Object

The identifer of the Sending Organisation (to be Base64 encoded).

Required
NHSD-Requesting-Practitioner

Object

The identifer of the Sending System User (to be Base64 encoded).

NHSD-Requesting-Person

Object

The identifer of the Sending Person (to be Base64 encoded).

NHSD-Requesting-Software

Object

The identifer of the Sending System (to be Base64 encoded).

Body
Required

Content type: application/fhir+json

Example

Schema

Name Description
object
resourceType
string
Example: Bundle
meta
object
profile
array
string
Example: https://fhir.nhs.uk/StructureDefinition/BARSBundleMessage
type
string
Example: message

Content type: application/fhir+xml

Schema

Name Description
object
resourceType
string
Example: Bundle
meta
object
profile
array
string
Example: https://fhir.nhs.uk/StructureDefinition/BARSBundleMessage
type
string
Example: message

Response

HTTP status: 200

Success

Headers
Name Description
X-Correlation-Id

UUID (uuid)

The X-Correlation-ID from the request header, if supplied, mirrored back.

Example: 9562466f-c982-4bd5-bb0e-255e9f5e6689

X-Request-Id

UUID (uuid)

The X-Request-ID from the request header, if supplied, mirrored back.

Example: c1ab3fba-6bae-4ba4-b257-5a87c44d4a91

Body

Content type: application/fhir+json

Example

Schema

Name Description
object
resourceType
string
Example: Bundle
meta
object
profile
array
string
Example: https://fhir.nhs.uk/StructureDefinition/BARSBundleMessage
type
string
Example: message

Content type: application/fhir+xml

Schema

Name Description
object
resourceType
string
Example: Bundle
meta
object
profile
array
string
Example: https://fhir.nhs.uk/StructureDefinition/BARSBundleMessage
type
string
Example: message
HTTP status: 4XX

An error occurred as follows: | HTTP status | Error code | Description | | ----------- | -------------------------- | --------------------------------------------- | | 400 | SEND_BAD_REQUEST | The API was unable to process the request. | | 400 | REC_BAD_REQUEST | The Receiver has responded stating the message was malformed. | | 401 | SEND_UNAUTHORIZED | The API deemed you unauthorized to make this request. | | 401 | REC_UNAUTHORIZED | The receiver deemed you unauthorized to make request. | | 403 | SEND_FORBIDDEN | Missing or Expired Token. | | 404 | PROXY_NOT_FOUND | No related people exist for given NHS number. | | 404 | REC_NOT_FOUND | Patient record for given NHS number has been invalidated and not superseded by another NHS number. | | 405 | SEND_METHOD_NOT_ALLOWED | HTTP Verb is not correct for this scenario.| | 405 | REC_METHOD_NOT_ALLOWED | Receiver does not allow this.| | 405 | PROXY_METHOD_NOT_ALLOWED | Proxy does not allow this.| | 406 | SEND_NOT_ACCEPTABLE | Senders message had an incorrect content type defined for a response.| | 408 | REC_TIMEOUT | The downstream domain processing has not completed within the configured timeout period. | | 409 | SEND_CONFLICT | | | 409 | REC_CONFLICT | | | 409 | PROXY_CONFLICT | | | 422 | SEND_UNPROCESSABLE_ENTITY | Message was not malformed but deemed unprocessable. | | 422 | REC_UNPROCESSABLE_ENTITY | Message was not malformed but deemed unprocessable. |
| 422 | PROXY_UNPROCESSABLE_ENTITY | Message was not malformed but deemed unprocessable. |
| 429 | SEND_TOO_MANY_REQUESTS | The user has sent too many requests in a given amount of time| | 429 | REC_TOO_MANY_REQUESTS | The user has sent too many requests in a given amount of time|

Headers
Name Description
X-Correlation-Id

UUID (uuid)

The X-Correlation-ID from the request header, if supplied, mirrored back.

Example: 9562466f-c982-4bd5-bb0e-255e9f5e6689

X-Request-Id

UUID (uuid)

The X-Request-ID from the request header, if supplied, mirrored back.

Example: c1ab3fba-6bae-4ba4-b257-5a87c44d4a91

Body

Content type: application/fhir+json

Example

Schema

Name Description
object
resourceType
string
Example: OperationalOutcome
meta
object
profile
array
string
Example: https://fhir.nhs.uk/StructureDefinition/BARSOperationalOutcome
HTTP status: 5XX

An error occurred as follows: | HTTP status | Error code | Description | | ----------- | -------------------------- | --------------------------------------------- | | 500 | REC_SERVER_ERROR | The receiver server has encountered an Error processing the request. | | 500 | PROXY_SERVER_ERROR | Proxy Error. | | 501 | SEND_NOT_IMPLEMENTED | The Request was not recognized. | | 501 | REC_NOT_IMPLEMENTED | The Receiver did not recognize the request. | | 501 | PROXY_NOT_IMPLEMENTED | The Proxy did not recognize the request. | | 503 | REC_UNAVAILABLE | The Receiver was unavailable to service the request.| | 503 | PROXY_UNAVAILABLE | The Proxy was unavailable to service the request. |

Headers
Name Description
X-Correlation-Id

UUID (uuid)

The X-Correlation-ID from the request header, if supplied, mirrored back.

Example: 9562466f-c982-4bd5-bb0e-255e9f5e6689

X-Request-Id

UUID (uuid)

The X-Request-ID from the request header, if supplied, mirrored back.

Example: c1ab3fba-6bae-4ba4-b257-5a87c44d4a91

Body

Content type: application/fhir+json

Example

Schema

Name Description
object
resourceType
string
Example: OperationalOutcome
meta
object
profile
array
string
Example: https://fhir.nhs.uk/StructureDefinition/BARSOperationalOutcome

Endpoints: Metadata

Get Message Definition

get
/MessageDefinition

Get Message Definition

Request

Headers
Name Description
X-Request-ID

UUID (uuid)

The X-Request-ID from the request header, if supplied, mirrored back.

Example: c1ab3fba-6bae-4ba4-b257-5a87c44d4a91

Required
X-Correlation-ID

UUID (uuid)

The X-Correlation-ID from the request header, if supplied, mirrored back.

Example: 9562466f-c982-4bd5-bb0e-255e9f5e6689

Required
NHSD-Target-Identifier

Object

The identifier of the Target system

Required
NHSD-End-User-Organisation

Object

The identifer of the Sending Organisation (to be Base64 encoded).

Required
NHSD-Requesting-Practitioner

Object

The identifer of the Sending System User (to be Base64 encoded).

NHSD-Requesting-Person

Object

The identifer of the Sending Person (to be Base64 encoded).

NHSD-Requesting-Software

Object

The identifer of the Sending System (to be Base64 encoded).

Response

HTTP status: 200

Success

Headers
Name Description
X-Correlation-Id

UUID (uuid)

The X-Correlation-ID from the request header, if supplied, mirrored back.

Example: 9562466f-c982-4bd5-bb0e-255e9f5e6689

X-Request-Id

UUID (uuid)

The X-Request-ID from the request header, if supplied, mirrored back.

Example: c1ab3fba-6bae-4ba4-b257-5a87c44d4a91

Body

Content type: application/fhir+json

Schema

Name Description
object
resourceType
string
Example: MessageDefinition
meta
object
profile
array
string
Example: https://fhir.nhs.uk/StructureDefinition/BARSMessageDefinition

Content type: application/fhir+xml

Schema

Name Description
object
resourceType
string
Example: MessageDefinition
meta
object
profile
array
string
Example: https://fhir.nhs.uk/StructureDefinition/BARSMessageDefinition
HTTP status: 4XX

An error occurred as follows: | HTTP status | Error code | Description | | ----------- | -------------------------- | --------------------------------------------- | | 400 | SEND_BAD_REQUEST | The API was unable to process the request. | | 400 | REC_BAD_REQUEST | The Receiver has responded stating the message was malformed. | | 401 | SEND_UNAUTHORIZED | The API deemed you unauthorized to make this request. | | 401 | REC_UNAUTHORIZED | The receiver deemed you unauthorized to make request. | | 403 | SEND_FORBIDDEN | Missing or Expired Token. | | 404 | PROXY_NOT_FOUND | No related people exist for given NHS number. | | 404 | REC_NOT_FOUND | Patient record for given NHS number has been invalidated and not superseded by another NHS number. | | 405 | SEND_METHOD_NOT_ALLOWED | HTTP Verb is not correct for this scenario.| | 405 | REC_METHOD_NOT_ALLOWED | Receiver does not allow this.| | 405 | PROXY_METHOD_NOT_ALLOWED | Proxy does not allow this.| | 406 | SEND_NOT_ACCEPTABLE | Senders message had an incorrect content type defined for a response.| | 408 | REC_TIMEOUT | The downstream domain processing has not completed within the configured timeout period. | | 409 | SEND_CONFLICT | | | 409 | REC_CONFLICT | | | 409 | PROXY_CONFLICT | | | 422 | SEND_UNPROCESSABLE_ENTITY | Message was not malformed but deemed unprocessable. | | 422 | REC_UNPROCESSABLE_ENTITY | Message was not malformed but deemed unprocessable. |
| 422 | PROXY_UNPROCESSABLE_ENTITY | Message was not malformed but deemed unprocessable. |
| 429 | SEND_TOO_MANY_REQUESTS | The user has sent too many requests in a given amount of time| | 429 | REC_TOO_MANY_REQUESTS | The user has sent too many requests in a given amount of time|

Headers
Name Description
X-Correlation-Id

UUID (uuid)

The X-Correlation-ID from the request header, if supplied, mirrored back.

Example: 9562466f-c982-4bd5-bb0e-255e9f5e6689

X-Request-Id

UUID (uuid)

The X-Request-ID from the request header, if supplied, mirrored back.

Example: c1ab3fba-6bae-4ba4-b257-5a87c44d4a91

Body

Content type: application/fhir+json

Example

Schema

Name Description
object
resourceType
string
Example: OperationalOutcome
meta
object
profile
array
string
Example: https://fhir.nhs.uk/StructureDefinition/BARSOperationalOutcome
HTTP status: 5XX

An error occurred as follows: | HTTP status | Error code | Description | | ----------- | -------------------------- | --------------------------------------------- | | 500 | REC_SERVER_ERROR | The receiver server has encountered an Error processing the request. | | 500 | PROXY_SERVER_ERROR | Proxy Error. | | 501 | SEND_NOT_IMPLEMENTED | The Request was not recognized. | | 501 | REC_NOT_IMPLEMENTED | The Receiver did not recognize the request. | | 501 | PROXY_NOT_IMPLEMENTED | The Proxy did not recognize the request. | | 503 | REC_UNAVAILABLE | The Receiver was unavailable to service the request.| | 503 | PROXY_UNAVAILABLE | The Proxy was unavailable to service the request. |

Headers
Name Description
X-Correlation-Id

UUID (uuid)

The X-Correlation-ID from the request header, if supplied, mirrored back.

Example: 9562466f-c982-4bd5-bb0e-255e9f5e6689

X-Request-Id

UUID (uuid)

The X-Request-ID from the request header, if supplied, mirrored back.

Example: c1ab3fba-6bae-4ba4-b257-5a87c44d4a91

Body

Content type: application/fhir+json

Example

Schema

Name Description
object
resourceType
string
Example: OperationalOutcome
meta
object
profile
array
string
Example: https://fhir.nhs.uk/StructureDefinition/BARSOperationalOutcome

Get capability statement

get
/metadata

Get capability statement

Request

Headers
Name Description
X-Request-ID

UUID (uuid)

The X-Request-ID from the request header, if supplied, mirrored back.

Example: c1ab3fba-6bae-4ba4-b257-5a87c44d4a91

Required
X-Correlation-ID

UUID (uuid)

The X-Correlation-ID from the request header, if supplied, mirrored back.

Example: 9562466f-c982-4bd5-bb0e-255e9f5e6689

Required
NHSD-Target-Identifier

Object

The identifier of the Target system

Required
NHSD-End-User-Organisation

Object

The identifer of the Sending Organisation (to be Base64 encoded).

Required
NHSD-Requesting-Practitioner

Object

The identifer of the Sending System User (to be Base64 encoded).

NHSD-Requesting-Person

Object

The identifer of the Sending Person (to be Base64 encoded).

NHSD-Requesting-Software

Object

The identifer of the Sending System (to be Base64 encoded).

Response

HTTP status: 200

Success

Headers
Name Description
X-Correlation-Id

UUID (uuid)

The X-Correlation-ID from the request header, if supplied, mirrored back.

Example: 9562466f-c982-4bd5-bb0e-255e9f5e6689

X-Request-Id

UUID (uuid)

The X-Request-ID from the request header, if supplied, mirrored back.

Example: c1ab3fba-6bae-4ba4-b257-5a87c44d4a91

Body

Content type: application/fhir+json

Example

Schema

Name Description
object
resourceType
string
Example: CapabilityStatement
meta
object
profile
array
string
Example: https://fhir.nhs.uk/StructureDefinition/BARSMessageDefinition-ServiceRequest-Response
fhirVersion
string
Example: 4.0.1
status
string
Example: active

Content type: application/fhir+xml

Schema

Name Description
object
resourceType
string
Example: CapabilityStatement
meta
object
profile
array
string
Example: https://fhir.nhs.uk/StructureDefinition/BARSMessageDefinition-ServiceRequest-Response
fhirVersion
string
Example: 4.0.1
status
string
Example: active
HTTP status: 4XX

An error occurred as follows: | HTTP status | Error code | Description | | ----------- | -------------------------- | --------------------------------------------- | | 400 | SEND_BAD_REQUEST | The API was unable to process the request. | | 400 | REC_BAD_REQUEST | The Receiver has responded stating the message was malformed. | | 401 | SEND_UNAUTHORIZED | The API deemed you unauthorized to make this request. | | 401 | REC_UNAUTHORIZED | The receiver deemed you unauthorized to make request. | | 403 | SEND_FORBIDDEN | Missing or Expired Token. | | 404 | PROXY_NOT_FOUND | No related people exist for given NHS number. | | 404 | REC_NOT_FOUND | Patient record for given NHS number has been invalidated and not superseded by another NHS number. | | 405 | SEND_METHOD_NOT_ALLOWED | HTTP Verb is not correct for this scenario.| | 405 | REC_METHOD_NOT_ALLOWED | Receiver does not allow this.| | 405 | PROXY_METHOD_NOT_ALLOWED | Proxy does not allow this.| | 406 | SEND_NOT_ACCEPTABLE | Senders message had an incorrect content type defined for a response.| | 408 | REC_TIMEOUT | The downstream domain processing has not completed within the configured timeout period. | | 409 | SEND_CONFLICT | | | 409 | REC_CONFLICT | | | 409 | PROXY_CONFLICT | | | 422 | SEND_UNPROCESSABLE_ENTITY | Message was not malformed but deemed unprocessable. | | 422 | REC_UNPROCESSABLE_ENTITY | Message was not malformed but deemed unprocessable. |
| 422 | PROXY_UNPROCESSABLE_ENTITY | Message was not malformed but deemed unprocessable. |
| 429 | SEND_TOO_MANY_REQUESTS | The user has sent too many requests in a given amount of time| | 429 | REC_TOO_MANY_REQUESTS | The user has sent too many requests in a given amount of time|

Headers
Name Description
X-Correlation-Id

UUID (uuid)

The X-Correlation-ID from the request header, if supplied, mirrored back.

Example: 9562466f-c982-4bd5-bb0e-255e9f5e6689

X-Request-Id

UUID (uuid)

The X-Request-ID from the request header, if supplied, mirrored back.

Example: c1ab3fba-6bae-4ba4-b257-5a87c44d4a91

Body

Content type: application/fhir+json

Example

Schema

Name Description
object
resourceType
string
Example: OperationalOutcome
meta
object
profile
array
string
Example: https://fhir.nhs.uk/StructureDefinition/BARSOperationalOutcome
HTTP status: 5XX

An error occurred as follows: | HTTP status | Error code | Description | | ----------- | -------------------------- | --------------------------------------------- | | 500 | REC_SERVER_ERROR | The receiver server has encountered an Error processing the request. | | 500 | PROXY_SERVER_ERROR | Proxy Error. | | 501 | SEND_NOT_IMPLEMENTED | The Request was not recognized. | | 501 | REC_NOT_IMPLEMENTED | The Receiver did not recognize the request. | | 501 | PROXY_NOT_IMPLEMENTED | The Proxy did not recognize the request. | | 503 | REC_UNAVAILABLE | The Receiver was unavailable to service the request.| | 503 | PROXY_UNAVAILABLE | The Proxy was unavailable to service the request. |

Headers
Name Description
X-Correlation-Id

UUID (uuid)

The X-Correlation-ID from the request header, if supplied, mirrored back.

Example: 9562466f-c982-4bd5-bb0e-255e9f5e6689

X-Request-Id

UUID (uuid)

The X-Request-ID from the request header, if supplied, mirrored back.

Example: c1ab3fba-6bae-4ba4-b257-5a87c44d4a91

Body

Content type: application/fhir+json

Example

Schema

Name Description
object
resourceType
string
Example: OperationalOutcome
meta
object
profile
array
string
Example: https://fhir.nhs.uk/StructureDefinition/BARSOperationalOutcome

Endpoints: Referral

Get a specific referral

get
/ServiceRequest/{id}

Get a specific referral

Request

Path parameters
Name Description
id

UUID (uuid)

The identifier of the registry object.

Example: c3f6145e-1a26-4345-b3f2-dccbcba62049

Required
Headers
Name Description
X-Request-ID

UUID (uuid)

The X-Request-ID from the request header, if supplied, mirrored back.

Example: c1ab3fba-6bae-4ba4-b257-5a87c44d4a91

Required
X-Correlation-ID

UUID (uuid)

The X-Correlation-ID from the request header, if supplied, mirrored back.

Example: 9562466f-c982-4bd5-bb0e-255e9f5e6689

Required
NHSD-End-User-Organisation

Object

The identifer of the Sending Organisation (to be Base64 encoded).

Required
NHSD-Requesting-Practitioner

Object

The identifer of the Sending System User (to be Base64 encoded).

NHSD-Requesting-Person

Object

The identifer of the Sending Person (to be Base64 encoded).

NHSD-Requesting-Software

Object

The identifer of the Sending System (to be Base64 encoded).

Response

HTTP status: 200

Success

Headers
Name Description
X-Correlation-Id

UUID (uuid)

The X-Correlation-ID from the request header, if supplied, mirrored back.

Example: 9562466f-c982-4bd5-bb0e-255e9f5e6689

X-Request-Id

UUID (uuid)

The X-Request-ID from the request header, if supplied, mirrored back.

Example: c1ab3fba-6bae-4ba4-b257-5a87c44d4a91

Body

Content type: application/fhir+json

Example

Schema

Name Description
object
resourceType
string
Example: ServiceRequest
meta
object
profile
array
string
Example: https://fhir.nhs.uk/StructureDefinition/BARSServiceRequest

Content type: application/fhir+xml

Schema

Name Description
object
resourceType
string
Example: ServiceRequest
meta
object
profile
array
string
Example: https://fhir.nhs.uk/StructureDefinition/BARSServiceRequest
HTTP status: 4XX

An error occurred as follows: | HTTP status | Error code | Description | | ----------- | -------------------------- | --------------------------------------------- | | 400 | SEND_BAD_REQUEST | The API was unable to process the request. | | 400 | REC_BAD_REQUEST | The Receiver has responded stating the message was malformed. | | 401 | SEND_UNAUTHORIZED | The API deemed you unauthorized to make this request. | | 401 | REC_UNAUTHORIZED | The receiver deemed you unauthorized to make request. | | 403 | SEND_FORBIDDEN | Missing or Expired Token. | | 404 | PROXY_NOT_FOUND | No related people exist for given NHS number. | | 404 | REC_NOT_FOUND | Patient record for given NHS number has been invalidated and not superseded by another NHS number. | | 405 | SEND_METHOD_NOT_ALLOWED | HTTP Verb is not correct for this scenario.| | 405 | REC_METHOD_NOT_ALLOWED | Receiver does not allow this.| | 405 | PROXY_METHOD_NOT_ALLOWED | Proxy does not allow this.| | 406 | SEND_NOT_ACCEPTABLE | Senders message had an incorrect content type defined for a response.| | 408 | REC_TIMEOUT | The downstream domain processing has not completed within the configured timeout period. | | 409 | SEND_CONFLICT | | | 409 | REC_CONFLICT | | | 409 | PROXY_CONFLICT | | | 422 | SEND_UNPROCESSABLE_ENTITY | Message was not malformed but deemed unprocessable. | | 422 | REC_UNPROCESSABLE_ENTITY | Message was not malformed but deemed unprocessable. |
| 422 | PROXY_UNPROCESSABLE_ENTITY | Message was not malformed but deemed unprocessable. |
| 429 | SEND_TOO_MANY_REQUESTS | The user has sent too many requests in a given amount of time| | 429 | REC_TOO_MANY_REQUESTS | The user has sent too many requests in a given amount of time|

Headers
Name Description
X-Correlation-Id

UUID (uuid)

The X-Correlation-ID from the request header, if supplied, mirrored back.

Example: 9562466f-c982-4bd5-bb0e-255e9f5e6689

X-Request-Id

UUID (uuid)

The X-Request-ID from the request header, if supplied, mirrored back.

Example: c1ab3fba-6bae-4ba4-b257-5a87c44d4a91

Body

Content type: application/fhir+json

Example

Schema

Name Description
object
resourceType
string
Example: OperationalOutcome
meta
object
profile
array
string
Example: https://fhir.nhs.uk/StructureDefinition/BARSOperationalOutcome
HTTP status: 5XX

An error occurred as follows: | HTTP status | Error code | Description | | ----------- | -------------------------- | --------------------------------------------- | | 500 | REC_SERVER_ERROR | The receiver server has encountered an Error processing the request. | | 500 | PROXY_SERVER_ERROR | Proxy Error. | | 501 | SEND_NOT_IMPLEMENTED | The Request was not recognized. | | 501 | REC_NOT_IMPLEMENTED | The Receiver did not recognize the request. | | 501 | PROXY_NOT_IMPLEMENTED | The Proxy did not recognize the request. | | 503 | REC_UNAVAILABLE | The Receiver was unavailable to service the request.| | 503 | PROXY_UNAVAILABLE | The Proxy was unavailable to service the request. |

Headers
Name Description
X-Correlation-Id

UUID (uuid)

The X-Correlation-ID from the request header, if supplied, mirrored back.

Example: 9562466f-c982-4bd5-bb0e-255e9f5e6689

X-Request-Id

UUID (uuid)

The X-Request-ID from the request header, if supplied, mirrored back.

Example: c1ab3fba-6bae-4ba4-b257-5a87c44d4a91

Body

Content type: application/fhir+json

Example

Schema

Name Description
object
resourceType
string
Example: OperationalOutcome
meta
object
profile
array
string
Example: https://fhir.nhs.uk/StructureDefinition/BARSOperationalOutcome

Get referral/s for a patient

get
/ServiceRequest

Get referral/s for a patient

Request

Query parameters
Name Description
patientIdentifier

String

The identifier of a patient.

Example: 485 777 3456

Required
Headers
Name Description
X-Request-ID

UUID (uuid)

The X-Request-ID from the request header, if supplied, mirrored back.

Example: c1ab3fba-6bae-4ba4-b257-5a87c44d4a91

Required
X-Correlation-ID

UUID (uuid)

The X-Correlation-ID from the request header, if supplied, mirrored back.

Example: 9562466f-c982-4bd5-bb0e-255e9f5e6689

Required
NHSD-End-User-Organisation

Object

The identifer of the Sending Organisation (to be Base64 encoded).

Required
NHSD-Requesting-Practitioner

Object

The identifer of the Sending System User (to be Base64 encoded).

NHSD-Requesting-Person

Object

The identifer of the Sending Person (to be Base64 encoded).

NHSD-Requesting-Software

Object

The identifer of the Sending System (to be Base64 encoded).

Response

HTTP status: 200

Success

Headers
Name Description
X-Correlation-Id

UUID (uuid)

The X-Correlation-ID from the request header, if supplied, mirrored back.

Example: 9562466f-c982-4bd5-bb0e-255e9f5e6689

X-Request-Id

UUID (uuid)

The X-Request-ID from the request header, if supplied, mirrored back.

Example: c1ab3fba-6bae-4ba4-b257-5a87c44d4a91

Body

Content type: application/fhir+json

Example

Schema

Name Description
object
resourceType
string
Example: Bundle
meta
object
profile
array
string
Example: https://fhir.nhs.uk/StructureDefinition/BARSBundle
type
string
Example: searchset

Content type: application/fhir+xml

Schema

Name Description
object
resourceType
string
Example: Bundle
meta
object
profile
array
string
Example: https://fhir.nhs.uk/StructureDefinition/BARSBundle
type
string
Example: searchset
HTTP status: 4XX

An error occurred as follows: | HTTP status | Error code | Description | | ----------- | -------------------------- | --------------------------------------------- | | 400 | SEND_BAD_REQUEST | The API was unable to process the request. | | 400 | REC_BAD_REQUEST | The Receiver has responded stating the message was malformed. | | 401 | SEND_UNAUTHORIZED | The API deemed you unauthorized to make this request. | | 401 | REC_UNAUTHORIZED | The receiver deemed you unauthorized to make request. | | 403 | SEND_FORBIDDEN | Missing or Expired Token. | | 404 | PROXY_NOT_FOUND | No related people exist for given NHS number. | | 404 | REC_NOT_FOUND | Patient record for given NHS number has been invalidated and not superseded by another NHS number. | | 405 | SEND_METHOD_NOT_ALLOWED | HTTP Verb is not correct for this scenario.| | 405 | REC_METHOD_NOT_ALLOWED | Receiver does not allow this.| | 405 | PROXY_METHOD_NOT_ALLOWED | Proxy does not allow this.| | 406 | SEND_NOT_ACCEPTABLE | Senders message had an incorrect content type defined for a response.| | 408 | REC_TIMEOUT | The downstream domain processing has not completed within the configured timeout period. | | 409 | SEND_CONFLICT | | | 409 | REC_CONFLICT | | | 409 | PROXY_CONFLICT | | | 422 | SEND_UNPROCESSABLE_ENTITY | Message was not malformed but deemed unprocessable. | | 422 | REC_UNPROCESSABLE_ENTITY | Message was not malformed but deemed unprocessable. |
| 422 | PROXY_UNPROCESSABLE_ENTITY | Message was not malformed but deemed unprocessable. |
| 429 | SEND_TOO_MANY_REQUESTS | The user has sent too many requests in a given amount of time| | 429 | REC_TOO_MANY_REQUESTS | The user has sent too many requests in a given amount of time|

Headers
Name Description
X-Correlation-Id

UUID (uuid)

The X-Correlation-ID from the request header, if supplied, mirrored back.

Example: 9562466f-c982-4bd5-bb0e-255e9f5e6689

X-Request-Id

UUID (uuid)

The X-Request-ID from the request header, if supplied, mirrored back.

Example: c1ab3fba-6bae-4ba4-b257-5a87c44d4a91

Body

Content type: application/fhir+json

Example

Schema

Name Description
object
resourceType
string
Example: OperationalOutcome
meta
object
profile
array
string
Example: https://fhir.nhs.uk/StructureDefinition/BARSOperationalOutcome
HTTP status: 5XX

An error occurred as follows: | HTTP status | Error code | Description | | ----------- | -------------------------- | --------------------------------------------- | | 500 | REC_SERVER_ERROR | The receiver server has encountered an Error processing the request. | | 500 | PROXY_SERVER_ERROR | Proxy Error. | | 501 | SEND_NOT_IMPLEMENTED | The Request was not recognized. | | 501 | REC_NOT_IMPLEMENTED | The Receiver did not recognize the request. | | 501 | PROXY_NOT_IMPLEMENTED | The Proxy did not recognize the request. | | 503 | REC_UNAVAILABLE | The Receiver was unavailable to service the request.| | 503 | PROXY_UNAVAILABLE | The Proxy was unavailable to service the request. |

Headers
Name Description
X-Correlation-Id

UUID (uuid)

The X-Correlation-ID from the request header, if supplied, mirrored back.

Example: 9562466f-c982-4bd5-bb0e-255e9f5e6689

X-Request-Id

UUID (uuid)

The X-Request-ID from the request header, if supplied, mirrored back.

Example: c1ab3fba-6bae-4ba4-b257-5a87c44d4a91

Body

Content type: application/fhir+json

Example

Schema

Name Description
object
resourceType
string
Example: OperationalOutcome
meta
object
profile
array
string
Example: https://fhir.nhs.uk/StructureDefinition/BARSOperationalOutcome

Endpoints: Slots

Get slots

get
/Slot

Get slots

Request

Query parameters
Name Description
status

array[String]

Status values that need to be considered for filter

Required
start

String (datetime)

Slot end date/time (yyyy-mm-ddThh:mm:ss+hh:mm)

Start and end represent the definition of the time window within which Slots must start

Example: 2020-03-31T14:00:00+00:00

Required
end

String (datetime)

Slot end date/time (yyyy-mm-ddThh:mm:ss+hh:mm)

Start and end represent the definition of the time window within which Slots must start

Example: 2020-03-31T16:00:00+00:00

Required
_include

array[String]

Inclusions that drive the rescusive depth of the search

Inclusion Description
Schedule Include Schedule Resources referenced within the Slot Resources
Practitioner Include Practitioner Resources referenced within the Schedule Resources
PractitionerRole Include Practitioner Role Resources referenced within the Schedule Resources
HealthcareService Include HealthcareService Resources referenced within the Schedule Resources
ProvidedBy Include Organization Resources referenced within the HealthcareService Resources
Location Include Location Resources referenced within the HealthcareService Resources
Required
Headers
Name Description
X-Request-ID

UUID (uuid)

The X-Request-ID from the request header, if supplied, mirrored back.

Example: c1ab3fba-6bae-4ba4-b257-5a87c44d4a91

Required
X-Correlation-ID

UUID (uuid)

The X-Correlation-ID from the request header, if supplied, mirrored back.

Example: 9562466f-c982-4bd5-bb0e-255e9f5e6689

Required
NHSD-Target-Identifier

Object

The identifier of the Target system

Required
NHSD-End-User-Organisation

Object

The identifer of the Sending Organisation (to be Base64 encoded).

Required
NHSD-Requesting-Practitioner

Object

The identifer of the Sending System User (to be Base64 encoded).

NHSD-Requesting-Person

Object

The identifer of the Sending Person (to be Base64 encoded).

NHSD-Requesting-Software

Object

The identifer of the Sending System (to be Base64 encoded).

Response

HTTP status: 200

Success

Headers
Name Description
X-Correlation-Id

UUID (uuid)

The X-Correlation-ID from the request header, if supplied, mirrored back.

Example: 9562466f-c982-4bd5-bb0e-255e9f5e6689

X-Request-Id

UUID (uuid)

The X-Request-ID from the request header, if supplied, mirrored back.

Example: c1ab3fba-6bae-4ba4-b257-5a87c44d4a91

Body

Content type: application/fhir+json

Example

Schema

Name Description
object
resourceType
string
Example: Bundle
meta
object
profile
array
string
Example: https://fhir.nhs.uk/StructureDefinition/BARSBundle
type
string
Example: searchset

Content type: application/fhir+xml

Schema

Name Description
object
resourceType
string
Example: Bundle
meta
object
profile
array
string
Example: https://fhir.nhs.uk/StructureDefinition/BARSBundle
type
string
Example: searchset
HTTP status: 4XX

An error occurred as follows: | HTTP status | Error code | Description | | ----------- | -------------------------- | --------------------------------------------- | | 400 | SEND_BAD_REQUEST | The API was unable to process the request. | | 400 | REC_BAD_REQUEST | The Receiver has responded stating the message was malformed. | | 401 | SEND_UNAUTHORIZED | The API deemed you unauthorized to make this request. | | 401 | REC_UNAUTHORIZED | The receiver deemed you unauthorized to make request. | | 403 | SEND_FORBIDDEN | Missing or Expired Token. | | 404 | PROXY_NOT_FOUND | No related people exist for given NHS number. | | 404 | REC_NOT_FOUND | Patient record for given NHS number has been invalidated and not superseded by another NHS number. | | 405 | SEND_METHOD_NOT_ALLOWED | HTTP Verb is not correct for this scenario.| | 405 | REC_METHOD_NOT_ALLOWED | Receiver does not allow this.| | 405 | PROXY_METHOD_NOT_ALLOWED | Proxy does not allow this.| | 406 | SEND_NOT_ACCEPTABLE | Senders message had an incorrect content type defined for a response.| | 408 | REC_TIMEOUT | The downstream domain processing has not completed within the configured timeout period. | | 409 | SEND_CONFLICT | | | 409 | REC_CONFLICT | | | 409 | PROXY_CONFLICT | | | 422 | SEND_UNPROCESSABLE_ENTITY | Message was not malformed but deemed unprocessable. | | 422 | REC_UNPROCESSABLE_ENTITY | Message was not malformed but deemed unprocessable. |
| 422 | PROXY_UNPROCESSABLE_ENTITY | Message was not malformed but deemed unprocessable. |
| 429 | SEND_TOO_MANY_REQUESTS | The user has sent too many requests in a given amount of time| | 429 | REC_TOO_MANY_REQUESTS | The user has sent too many requests in a given amount of time|

Headers
Name Description
X-Correlation-Id

UUID (uuid)

The X-Correlation-ID from the request header, if supplied, mirrored back.

Example: 9562466f-c982-4bd5-bb0e-255e9f5e6689

X-Request-Id

UUID (uuid)

The X-Request-ID from the request header, if supplied, mirrored back.

Example: c1ab3fba-6bae-4ba4-b257-5a87c44d4a91

Body

Content type: application/fhir+json

Example

Schema

Name Description
object
resourceType
string
Example: OperationalOutcome
meta
object
profile
array
string
Example: https://fhir.nhs.uk/StructureDefinition/BARSOperationalOutcome
HTTP status: 5XX

An error occurred as follows: | HTTP status | Error code | Description | | ----------- | -------------------------- | --------------------------------------------- | | 500 | REC_SERVER_ERROR | The receiver server has encountered an Error processing the request. | | 500 | PROXY_SERVER_ERROR | Proxy Error. | | 501 | SEND_NOT_IMPLEMENTED | The Request was not recognized. | | 501 | REC_NOT_IMPLEMENTED | The Receiver did not recognize the request. | | 501 | PROXY_NOT_IMPLEMENTED | The Proxy did not recognize the request. | | 503 | REC_UNAVAILABLE | The Receiver was unavailable to service the request.| | 503 | PROXY_UNAVAILABLE | The Proxy was unavailable to service the request. |

Headers
Name Description
X-Correlation-Id

UUID (uuid)

The X-Correlation-ID from the request header, if supplied, mirrored back.

Example: 9562466f-c982-4bd5-bb0e-255e9f5e6689

X-Request-Id

UUID (uuid)

The X-Request-ID from the request header, if supplied, mirrored back.

Example: c1ab3fba-6bae-4ba4-b257-5a87c44d4a91

Body

Content type: application/fhir+json

Example

Schema

Name Description
object
resourceType
string
Example: OperationalOutcome
meta
object
profile
array
string
Example: https://fhir.nhs.uk/StructureDefinition/BARSOperationalOutcome