NHSDigital · nhsd-david-wass · Oct 16, 2025 · Oct 7, 2025 · Oct 7, 2025 · Oct 7, 2025
@@ -53,7 +53,7 @@ runs:
     - name: Upload API OAS specification artifact
       uses: actions/upload-artifact@v4
       with:
-        path: "specification/api"
+        path: "build"
         name: api-oas-specification-${{ inputs.version }}
 
     - name: Upload html artifact

@@ -2,7 +2,7 @@
   "data": {
     "attributes": {
       "groupId": "c5d93f917f5546d08beccf770a915d96",
-      "reasonCode": 100,
+      "reasonCode": "R01",
       "reasonText": "failed validation",
       "specificationId": "2WL5eYSWGzCHlGmzNxuqVusPxDg",
       "status": "REJECTED"

@@ -2,7 +2,7 @@
   "data": {
     "attributes": {
       "groupId": "c5d93f917f5546d08beccf770a915d96",
-      "reasonCode": 100,
+      "reasonCode": "R01",
       "specificationId": "2WL5eYSWGzCHlGmzNxuqVusPxDg",
       "status": "CANCELLED"
     },

@@ -2,7 +2,7 @@
   "data": {
     "attributes": {
       "groupId": "c5d93f917f5546d08beccf770a915d96",
-      "reasonCode": 100,
+      "reasonCode": "R01",
       "reasonText": "failed validation",
       "specificationId": "2WL5eYSWGzCHlGmzNxuqVusPxDg",
       "status": "FAILED"

@@ -2,7 +2,7 @@
   "data": {
     "attributes": {
       "groupId": "c5d93f917f5546d08beccf770a915d96",
-      "reasonCode": 100,
+      "reasonCode": "R01",
       "reasonText": "failed validation",
       "specificationId": "2WL5eYSWGzCHlGmzNxuqVusPxDg",
       "status": "RETURNED"

@@ -1,7 +1,7 @@
 {
   "data": {
     "attributes": {
-      "reasonCode": 100,
+      "reasonCode": "R01",
       "reasonText": "failed validation",
       "status": "CANCELLED"
     },

@@ -1,7 +1,7 @@
 {
   "data": {
     "attributes": {
-      "reasonCode": 100,
+      "reasonCode": "R01",
       "reasonText": "failed validation",
       "status": "FAILED"
     },

@@ -1,7 +1,7 @@
 {
   "data": {
     "attributes": {
-      "reasonCode": 100,
+      "reasonCode": "R01",
       "reasonText": "failed validation",
       "status": "REJECTED"
     },

@@ -1,7 +1,7 @@
 {
   "data": {
     "attributes": {
-      "reasonCode": 100,
+      "reasonCode": "R01",
       "reasonText": "failed validation",
       "status": "REJECTED"
     },

@@ -1,7 +1,7 @@
 {
   "data": {
     "attributes": {
-      "reasonCode": 100,
+      "reasonCode": "R01",
       "reasonText": "failed validation",
       "specificationId": "2WL5eYSWGzCHlGmzNxuqVusPxDg",
       "status": "CANCELLED"

@@ -1,7 +1,7 @@
 {
   "data": {
     "attributes": {
-      "reasonCode": 100,
+      "reasonCode": "R01",
       "reasonText": "failed validation",
       "specificationId": "2WL5eYSWGzCHlGmzNxuqVusPxDg",
       "status": "FAILED"

@@ -1,7 +1,7 @@
 {
   "data": {
     "attributes": {
-      "reasonCode": 100,
+      "reasonCode": "R01",
       "reasonText": "failed validation",
       "specificationId": "2WL5eYSWGzCHlGmzNxuqVusPxDg",
       "status": "REJECTED"

@@ -1,7 +1,7 @@
 {
   "data": {
     "attributes": {
-      "reasonCode": 100,
+      "reasonCode": "R01",
       "reasonText": "failed validation",
       "specificationId": "2WL5eYSWGzCHlGmzNxuqVusPxDg",
       "status": "RETURNED"

@@ -44,7 +44,7 @@
     },
     {
       "attributes": {
-        "reasonCode": 100,
+        "reasonCode": "R01",
         "reasonText": "failed validation",
         "status": "RETURNED"
       },
@@ -53,7 +53,7 @@
     },
     {
       "attributes": {
-        "reasonCode": 100,
+        "reasonCode": "R01",
         "reasonText": "failed validation",
         "status": "CANCELLED"
       },
@@ -62,7 +62,7 @@
     },
     {
       "attributes": {
-        "reasonCode": 100,
+        "reasonCode": "R01",
         "reasonText": "failed validation",
         "status": "FAILED"
       },
@@ -71,7 +71,7 @@
     },
     {
       "attributes": {
-        "reasonCode": 100,
+        "reasonCode": "R01",
         "reasonText": "failed validation",
         "status": "RETURNED"
       },

@@ -9,3 +9,6 @@ MD024:
 
 # https://github.com/DavidAnson/markdownlint/blob/main/doc/md033.md
 MD033: false
+
+MD041:
+  level: 2
@@ -20,7 +20,7 @@ Jira
 Makefile
 OAuth
 Octokit
-onboarding
+[Oo]nboarding
 Podman
 pre
 Python

@@ -0,0 +1,120 @@
+## 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](https://digital.nhs.uk/services/nhs-notify) platform.
+
+## Related APIs
+
+The [NHS Notify API](https://digital.nhs.uk/developer/api-catalogue/nhs-notify) 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](https://digital.nhs.uk/developer/guides-and-documentation/reference-guide#statuses). 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](https://digital.nhs.uk/services/reference-guide#service-levels) 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](https://digital.nhs.uk/developer/guides-and-documentation/reference-guide#service-levels).
+
+## Technology
+
+This API is a [REST-based](https://digital.nhs.uk/developer/guides-and-documentation/our-api-technologies#basic-rest) API.
+
+We follow the [JSON:API](https://jsonapi.org/) standard for our request and response schemas.
+
+### Response content types
+
+This API can generate responses in the following format:
+
+* `application/vnd.api+json` - see [JSON:API specification](https://jsonapi.org/format/#introduction)
+
+### Request content types
+
+This API will accept request payloads of the following types:
+
+* `application/vnd.api+json` - see [JSON:API specification](https://jsonapi.org/format/#introduction)
+* `application/json`
+
+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)](https://digital.nhs.uk/services/health-and-social-care-network).
+
+For more details see [Network access for APIs](https://digital.nhs.uk/developer/guides-and-documentation/network-access-for-apis).
+
+## Security and authorisation
+
+This API is [application-restricted](https://digital.nhs.uk/developer/guides-and-documentation/security-and-authorisation#application-restricted-apis), 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:
+
+* [Application-restricted RESTful API - signed JWT authentication](https://digital.nhs.uk/developer/guides-and-documentation/security-and-authorisation/application-restricted-restful-apis-signed-jwt-authentication)
+
+## 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](https://digital.nhs.uk/developer/guides-and-documentation/testing#sandbox-testing):
+
+* 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](https://github.com/NHSDigital/nhs-notify-supplier-api/tree/main/postman).
+
+### Integration testing
+
+Our integration test environment:
+
+* is for formal integration sandbox-testing
+* is stateful, so persists updates
+* includes authorisation via [signed JWT authentication](https://digital.nhs.uk/developer/guides-and-documentation/security-and-authorisation/application-restricted-restful-apis-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
@@ -0,0 +1,17 @@
+## 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|
@@ -0,0 +1,14 @@
+## 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](http://example.com) in the Location header |
+|Not Found |2WL5eYSWGzCHlGmzNxuqVusPxDg | Returns 404 Not found and error details in the response |
@@ -0,0 +1,22 @@
+## 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`|
@@ -0,0 +1,12 @@
+## 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) |
@@ -0,0 +1,8 @@
+## 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
@@ -0,0 +1,27 @@
+## 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.
-Original file line number
+Diff line change
@@ Expand Up / @@ -20,7 +20,7 @@ Jira @@
     Makefile
     OAuth
     Octokit
-    onboarding
+    [Oo]nboarding
     Podman
     pre
     Python
@@ Expand Down @@