NHS Notify Supplier API

NHS Notify Supplier API

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

More information: https://openapi-generator.tech
Contact Info: team@openapitools.org
Version: next
BasePath:/nhs-notify-supplier
All rights reserved
http://apache.org/licenses/LICENSE-2.0.html

Access

  1. OAuth AuthorizationUrl:TokenUrl:/oauth2/token
  2. APIKey KeyParamName:apikey KeyInQuery:false KeyInHeader:true

Methods

[ Jump to Models ]

Table of Contents

Data

Default

Letter

Mi

Data

Up
get /letters/{id}/data
Fetch a data file (getDataId)

Overview

Use this endpoint to get letter data, including downloading the letter's print-ready PDF file.

Rate limiting applies. On excess requests, you may receive 429 Too Many Requests (example error code(s): NOTIFY_QUOTA). Back off and retry later

Sandbox test scenarios

You can test the following scenarios in our sandbox environment.

|Scenario|Request ID|Response| |--------|-------|--------| |Success | 2AL5eYSWGzCHlGmzNxuqVusPxDg | Returns 303 (See Other) and URL to http://example.com in the Location header | |Not Found |2WL5eYSWGzCHlGmzNxuqVusPxDg | Returns 404 Not found and error details in the response |

Path parameters

id (required)
Path Parameter — Unique identifier of this resource default: null

Request headers

X-Request-ID (required)
Header Parameter — Unique request identifier, in the format of a GUID default: null
X-Correlation-ID (optional)
Header Parameter — An optional ID which you can use to track transactions across multiple systems. It can take any value, but we recommend avoiding . characters. If not provided in the request, NHS Notify will default to a system generated ID in its place. The ID will be returned in a response header. default: null

Example data

Content-Type: application/vnd.api+json
Custom MIME type example not yet supported: application/vnd.api+json

Example data

Content-Type: application/vnd.api+json
Custom MIME type example not yet supported: application/vnd.api+json

Example data

Content-Type: application/vnd.api+json
Custom MIME type example not yet supported: application/vnd.api+json

Produces

This API call produces the following media types according to the Accept request header; the media type will be conveyed by the Content-Type response header.
  • application/vnd.api+json

Responses

303

See Other

404

Resource not found listLetters_400_response

429

Too many requests listLetters_400_response

500

Server error listLetters_400_response
Up
head /letters/{id}/data
Check for the existence of a data file (headDataId)

Overview

Use this endpoint to check for the existence of letter data. This is useful for verifying readiness before performing retrieval or print operations.

Sandbox test scenarios

You can test the following scenarios in our sandbox environment.

|Scenario|Request ID|Response| |--------|-------|--------| |Success | 2AL5eYSWGzCHlGmzNxuqVusPxDg | Returns 200 (OK)| |Not Found |2WL5eYSWGzCHlGmzNxuqVusPxDg | Returns 404 (Not found) |

Path parameters

id (required)
Path Parameter — Unique identifier of this resource default: null

Request headers

X-Request-ID (required)
Header Parameter — Unique request identifier, in the format of a GUID default: null
X-Correlation-ID (optional)
Header Parameter — An optional ID which you can use to track transactions across multiple systems. It can take any value, but we recommend avoiding . characters. If not provided in the request, NHS Notify will default to a system generated ID in its place. The ID will be returned in a response header. default: null

Responses

200

OK

Default

Up
get /_status
Health check endpoint (getStatus)
Returns 200 OK if the service is up.

Responses

200

Service is healthy

Letter

Up
get /letters/{id}
Retrieve the status of a letter (getLetterStatus)

Overview

Use this endpoint to get the current status of a single letter by its ID.

Rate limiting applies. On excess requests, you may receive 429 Too Many Requests (example error code(s): NOTIFY_QUOTA). Back off and retry later

Sandbox test scenarios

You can test the following scenarios in our sandbox environment

| Scenario | Letter Id | | ----------------------------------------| ---------------------------- | | Retrieve a PENDING letter status | 24L5eYSWGzCHlGmzNxuqVusPxDg| | Retrieve a ACCEPTED letter status | 2AL5eYSWGzCHlGmzNxuqVusPxDg| | Retrieve a PRINTED letter status | 2BL5eYSWGzCHlGmzNxuqVusPxDg| | Retrieve a ENCLOSED letter status | 2CL5eYSWGzCHlGmzNxuqVusPxDg| | Retrieve a DISPATCHED letter status | 2DL5eYSWGzCHlGmzNxuqVusPxDg| | Retrieve a DELIVERED letter status | 2EL5eYSWGzCHlGmzNxuqVusPxDg| | Retrieve a REJECTED letter status | 2WL5eYSWGzCHlGmzNxuqVusPxDg| | Retrieve a CANCELLED letter status | 2XL5eYSWGzCHlGmzNxuqVusPxDg| | Retrieve a FAILED letter status | 2YL5eYSWGzCHlGmzNxuqVusPxDg| | Retrieve a RETURNED letter status | 2ZL5eYSWGzCHlGmzNxuqVusPxDg|

Path parameters

id (required)
Path Parameter — Unique identifier of this resource default: null

Request headers

X-Request-ID (required)
Header Parameter — Unique request identifier, in the format of a GUID default: null
X-Correlation-ID (optional)
Header Parameter — An optional ID which you can use to track transactions across multiple systems. It can take any value, but we recommend avoiding . characters. If not provided in the request, NHS Notify will default to a system generated ID in its place. The ID will be returned in a response header. default: null

Return type

getLetterStatus_200_response

Example data

Content-Type: application/vnd.api+json
Custom MIME type example not yet supported: application/vnd.api+json

Example data

Content-Type: application/vnd.api+json
Custom MIME type example not yet supported: application/vnd.api+json

Example data

Content-Type: application/vnd.api+json
Custom MIME type example not yet supported: application/vnd.api+json

Example data

Content-Type: application/vnd.api+json
Custom MIME type example not yet supported: application/vnd.api+json

Produces

This API call produces the following media types according to the Accept request header; the media type will be conveyed by the Content-Type response header.
  • application/vnd.api+json

Responses

200

Letter status getLetterStatus_200_response

404

Resource not found listLetters_400_response

429

Too many requests listLetters_400_response

500

Server error listLetters_400_response
Up
get /letters
Get a list of PENDING letters (listLetters)

Overview

Use this endpoint to poll letters which are ready to be printed.

Returns letters whose status is PENDING. Use limit to control list size (max 2500).

Rate limiting applies. On excess requests, you may receive 429 Too Many Requests (example error code(s): NOTIFY_QUOTA). Back off and retry later

Request headers

X-Request-ID (required)
Header Parameter — Unique request identifier, in the format of a GUID default: null
X-Correlation-ID (optional)
Header Parameter — An optional ID which you can use to track transactions across multiple systems. It can take any value, but we recommend avoiding . characters. If not provided in the request, NHS Notify will default to a system generated ID in its place. The ID will be returned in a response header. default: null

Query parameters

limit (optional)
Query Parameter — The maximum number of items to return in a single request, max 2500 default: null

Return type

listLetters_200_response

Example data

Content-Type: application/vnd.api+json
Custom MIME type example not yet supported: application/vnd.api+json

Example data

Content-Type: application/vnd.api+json
Custom MIME type example not yet supported: application/vnd.api+json

Example data

Content-Type: application/vnd.api+json
Custom MIME type example not yet supported: application/vnd.api+json

Example data

Content-Type: application/vnd.api+json
Custom MIME type example not yet supported: application/vnd.api+json

Example data

Content-Type: application/vnd.api+json
Custom MIME type example not yet supported: application/vnd.api+json

Produces

This API call produces the following media types according to the Accept request header; the media type will be conveyed by the Content-Type response header.
  • application/vnd.api+json

Responses

200

List of letters to process listLetters_200_response

400

Bad request, invalid input data listLetters_400_response

404

Resource not found listLetters_400_response

429

Too many requests listLetters_400_response

500

Server error listLetters_400_response
Up
patch /letters/{id}
Update the status of a letter (patchLetter)

Overview

Use this endpoint to update the status of a letter by submitting the new status in the request body, optionally providing a reason code and text.

When you make a PATCH request with your application, the endpoint will respond with a successful (200) response code, along with the updated patient resource or an unsuccessful (4xx/5xx) response.

Rate limiting applies. On excess requests, you may receive 429 Too Many Requests (example error code(s): NOTIFY_QUOTA). Back off and retry later.

Statuses

Allowed status values that can be used to are:

  • ACCEPTED
  • CANCELLED
  • DELIVERED
  • DESTROYED
  • DISPATCHED
  • ENCLOSED
  • FAILED
  • FORWARDED
  • PRINTED
  • REJECTED
  • RETURNED

It is not possible to update a letter to status of PENDING.

Optionally a reasonCode and reasonText explaining the status (for example, validation failures) can be included in the request body.

Path parameters

id (required)
Path Parameter — Unique identifier of this resource default: null

Consumes

This API call consumes the following media types via the Content-Type request header:
  • application/vnd.api+json

Request body

patchLetter_request patchLetter_request (optional)
Body Parameter —

Request headers

X-Request-ID (required)
Header Parameter — Unique request identifier, in the format of a GUID default: null
X-Correlation-ID (optional)
Header Parameter — An optional ID which you can use to track transactions across multiple systems. It can take any value, but we recommend avoiding . characters. If not provided in the request, NHS Notify will default to a system generated ID in its place. The ID will be returned in a response header. default: null

Return type

getLetterStatus_200_response

Example data

Content-Type: application/vnd.api+json
Custom MIME type example not yet supported: application/vnd.api+json

Example data

Content-Type: application/vnd.api+json
Custom MIME type example not yet supported: application/vnd.api+json

Example data

Content-Type: application/vnd.api+json
Custom MIME type example not yet supported: application/vnd.api+json

Example data

Content-Type: application/vnd.api+json
Custom MIME type example not yet supported: application/vnd.api+json

Example data

Content-Type: application/vnd.api+json
Custom MIME type example not yet supported: application/vnd.api+json

Produces

This API call produces the following media types according to the Accept request header; the media type will be conveyed by the Content-Type response header.
  • application/vnd.api+json

Responses

200

Letter resource updated successfully getLetterStatus_200_response

400

Bad request, invalid input data listLetters_400_response

404

Resource not found listLetters_400_response

429

Too many requests listLetters_400_response

500

Server error listLetters_400_response
Up
post /letters
Update the status of multiple letters (postLetters)

Overview

Use this endpoint to update the status for (example, PRINTED, DISPATCHED, DELIVERED) of multiple letters by providing the new statuses in the request body, optionally including reason codes and text.

Use this endpoint when you need to report status changes for several letters at once.

When you make a POST update request with, the endpoint will respond with a successful (202) response code or an unsuccessful (4xx/5xx) response.

Rate limiting applies. On excess requests, you may receive 429 Too Many Requests (example error code(s): NOTIFY_QUOTA). Back off and retry later.

Statuses

Allowed status values that can be used to are:

  • ACCEPTED
  • CANCELLED
  • DELIVERED
  • DESTROYED
  • DISPATCHED
  • ENCLOSED
  • FAILED
  • FORWARDED
  • PRINTED
  • REJECTED
  • RETURNED

It is not possible to update a letter to status of PENDING.

Optionally a reasonCode and reasonText explaining the status (for example, validation failures) can be included in the request body for each update.

Consumes

This API call consumes the following media types via the Content-Type request header:
  • application/vnd.api+json

Request body

postLetters_request postLetters_request (optional)
Body Parameter —

Request headers

X-Request-ID (required)
Header Parameter — Unique request identifier, in the format of a GUID default: null
X-Correlation-ID (optional)
Header Parameter — An optional ID which you can use to track transactions across multiple systems. It can take any value, but we recommend avoiding . characters. If not provided in the request, NHS Notify will default to a system generated ID in its place. The ID will be returned in a response header. default: null

Example data

Content-Type: application/vnd.api+json
Custom MIME type example not yet supported: application/vnd.api+json

Example data

Content-Type: application/vnd.api+json
Custom MIME type example not yet supported: application/vnd.api+json

Example data

Content-Type: application/vnd.api+json
Custom MIME type example not yet supported: application/vnd.api+json

Produces

This API call produces the following media types according to the Accept request header; the media type will be conveyed by the Content-Type response header.
  • application/vnd.api+json

Responses

202

202 (Accepted) Acknowledges that status updates have been posted

404

Resource not found listLetters_400_response

429

Too many requests listLetters_400_response

500

Server error listLetters_400_response

Mi

Up
post /mi
Create a new MI record (createMI)

Overview

Use this endpoint to send management or operational metrics relating to letter processing and print fulfilment

When you submit a create management information request, the endpoint will respond with a c201 (Created) response code along with the created data including a unique id for the record or an unsuccessful (4xx/5xx) response

Rate limiting applies. On excess requests, you may receive 429 Too Many Requests (example error code(s): NOTIFY_QUOTA). Back off and retry later

Sandbox test scenarios

You can test the following scenarios in our sandbox environment.

|Scenario|Request|Response| |--------|-------|--------| |Success|Request for successful MI record Creation| 201 (Created) with the created management information in the response| |Invalid Request|Invalid Request for MI record Creation| 400 (Bad Request) with the error details in the body| |Unknown specification|Request for MI record Creation for unknown spec|404 (Not Found) with the error details in the body|

Consumes

This API call consumes the following media types via the Content-Type request header:
  • application/vnd.api+json

Request body

createMI_request createMI_request (optional)
Body Parameter —

Request headers

X-Request-ID (required)
Header Parameter — Unique request identifier, in the format of a GUID default: null
X-Correlation-ID (optional)
Header Parameter — An optional ID which you can use to track transactions across multiple systems. It can take any value, but we recommend avoiding . characters. If not provided in the request, NHS Notify will default to a system generated ID in its place. The ID will be returned in a response header. default: null

Return type

createMI_201_response

Example data

Content-Type: application/vnd.api+json
Custom MIME type example not yet supported: application/vnd.api+json

Example data

Content-Type: application/vnd.api+json
Custom MIME type example not yet supported: application/vnd.api+json

Example data

Content-Type: application/vnd.api+json
Custom MIME type example not yet supported: application/vnd.api+json

Example data

Content-Type: application/vnd.api+json
Custom MIME type example not yet supported: application/vnd.api+json

Example data

Content-Type: application/vnd.api+json
Custom MIME type example not yet supported: application/vnd.api+json

Produces

This API call produces the following media types according to the Accept request header; the media type will be conveyed by the Content-Type response header.
  • application/vnd.api+json

Responses

201

Management Information created successfully createMI_201_response

400

Bad request, invalid input data listLetters_400_response

404

Resource not found listLetters_400_response

429

Too many requests listLetters_400_response

500

Server error listLetters_400_response

Models

[ Jump to Methods ]

Table of Contents

  1. createMI_201_response -
  2. createMI_201_response_data -
  3. createMI_request -
  4. createMI_request_data -
  5. createMI_request_data_attributes -
  6. getLetterStatus_200_response -
  7. listLetters_200_response -
  8. listLetters_200_response_data_inner -
  9. listLetters_200_response_data_inner_attributes -
  10. listLetters_400_response -
  11. listLetters_400_response_errors_inner -
  12. listLetters_400_response_errors_inner_links -
  13. patchLetter_request -
  14. postLetters_request -
  15. postLetters_request_data_inner -
  16. postLetters_request_data_inner_attributes -

createMI_201_response - Up

data (optional)
createMI_201_response_data

createMI_201_response_data - Up

type (optional)
String
Enum:
ManagementInformation
id (optional)
String
attributes (optional)
createMI_request_data_attributes

createMI_request - Up

data (optional)
createMI_request_data

createMI_request_data - Up

type
String
Enum:
ManagementInformation
attributes
createMI_request_data_attributes

createMI_request_data_attributes - Up

lineItem
String A line item reference that should match an invoice line item
timestamp
Date The effective date of the activity being reported format: date-time
quantity
BigDecimal The quantity of the line item being reported
specificationId (optional)
String A specification ID provided in the Letter request that this MI relates to
groupId (optional)
String A group ID provided in the Letter request that this MI relates to
stockRemaining (optional)
BigDecimal Stock remaining for this line item, where applicable

getLetterStatus_200_response - Up

data
listLetters_200_response_data_inner

listLetters_200_response - Up

data (optional)
array[listLetters_200_response_data_inner]

listLetters_200_response_data_inner - Up

type (optional)
String
Enum:
Letter
id (optional)
String
attributes (optional)
listLetters_200_response_data_inner_attributes

listLetters_200_response_data_inner_attributes - Up

specificationId
String
groupId (optional)
String
status
String The supplier status of an individual letter
Enum:
PENDING
ACCEPTED
REJECTED
PRINTED
ENCLOSED
CANCELLED
DISPATCHED
DELIVERED
FAILED
RETURNED
DESTROYED
FORWARDED
reasonCode (optional)
String Reason code for the given status
reasonText (optional)
String Reason text for the given status

listLetters_400_response - Up

errors (optional)
array[listLetters_400_response_errors_inner]

listLetters_400_response_errors_inner - Up

id (optional)
String
code (optional)
String
Enum:
NOTIFY_INTERNAL_SERVER_ERROR
NOTIFY_INVALID_REQUEST
NOTIFY_LETTER_NOT_FOUND
links (optional)
listLetters_400_response_errors_inner_links
status (optional)
String
title (optional)
String
detail (optional)
String

listLetters_400_response_errors_inner_links - Up

about (optional)
URI format: uri

patchLetter_request - Up

data
postLetters_request_data_inner

postLetters_request - Up

data
array[postLetters_request_data_inner]

postLetters_request_data_inner - Up

type
String
Enum:
Letter
id
String
attributes
postLetters_request_data_inner_attributes

postLetters_request_data_inner_attributes - Up

status
String The supplier status of an individual letter
Enum:
PENDING
ACCEPTED
REJECTED
PRINTED
ENCLOSED
CANCELLED
DISPATCHED
DELIVERED
FAILED
RETURNED
DESTROYED
FORWARDED
reasonCode (optional)
String Reason code for the given status
reasonText (optional)
String Reason text for the given status