Skip to content

APIDescription.md

Latest commit

 

History

History
120 lines (70 loc) · 5.76 KB

APIDescription.md

File metadata and controls

120 lines (70 loc) · 5.76 KB

Overview

API for letter suppliers to integrate with NHS Notify.

This API lets you:

  • Get lists of letters allocated to you
  • Download letter PDFs and metadata
  • Update and manage letter statuses
  • Submit and retrieve management information (MI)

This specification represents the in-development 'next' version of the API schema and should be treated as unstable

Use this API to retrieve letters to be printed

Who can use this API

The NHS Notify Supplier API is designed for approved print service suppliers who support the delivery of physical letters through the NHS Notify platform.

Related APIs

The NHS Notify API is used to send messages to citizens via NHS App, email, text message or letter.

API status and roadmap

This API is in production, beta. We are onboarding partners to use it.

We may make additive non-breaking changes to the API without notice, for example the addition of fields to a response or callback, or new optional fields to a request.

Service Level

This service is a silver service, meaning it is available 24 hours a day, 365 days a year and supported from 8am to 6pm, Monday to Friday excluding bank holidays. For more details, see service levels.

Technology

This API is a REST-based API.

We follow the JSON:API standard for our request and response schemas.

Response content types

This API can generate responses in the following format:

Request content types

This API will accept request payloads of the following types:

The Content-Type header may optionally include a charset attribute. If included, it must be set to charset=utf-8 Any other charset value will result in a 406 error response. If omitted then utf-8 is assumed.

If you attempt to send a payload without the Content-Type header set to either of these values then the API will respond with a 415 Unsupported Media Type response.

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 application-restricted, meaning we authenticate the calling application but not the end user.

Authentication and authorisation of end users is the responsibility of your application.

To access this API, use the following security pattern:

Environments and testing

Environment Base URL
Sandbox https://sandbox.api.service.nhs.uk/nhs-notify-supplier
Integration test https://int.api.service.nhs.uk/nhs-notify-supplier
Production https://api.service.nhs.uk/nhs-notify-supplier

Sandbox testing

Our sandbox environment:

  • is for early developer testing
  • only covers a limited set of scenarios
  • is stateless, so does not actually persist any updates
  • is open access, so does not allow you to test authorisation

For details of sandbox test scenarios, or to try out sandbox using our 'Try this API' feature, see the documentation for each endpoint.

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

You can find our postman collection source in our public repository on github.

Integration testing

Our integration test environment:

  • is for formal integration sandbox-testing
  • is stateful, so persists updates
  • includes authorisation via signed JWT authentication

You need to get your software approved by us before it can go live with this API.

You will also need to follow our steps to - TBD

Production smoke testing

Before go-live, you must complete a smoke test in the NHS Notify production environment. The smoke test confirms that your live credentials, connectivity, and print workflow operate correctly end-to-end. It will be carried out in coordination with the NHS Notify Supplier API team. You will retrieve and print one or more live test letters through the production API, send the printed output to the address provided, and submit a Management Information (MI) update for verification. The NHS Notify team will configure your production access, review your results, and confirm that your output meets NHS Notify print specifications.

Onboarding

You need to get your software approved by us before it can go live with this API. You will also need to be an approved NHS letter supplier under the framework agreement (ADD link) and nominate your technical and operational contacts