Review Comments

Author: nhsd-david-wass

scripts/config/vale/styles/config/vocabularies/words/accept.txt

@@ -20,7 +20,7 @@ Jira
 Makefile
 OAuth
 Octokit
-onboarding
+[Oo]nboarding
 Podman
 pre
 Python

specification/api/components/documentation/APIDescription.md

@@ -1,6 +1,13 @@
 ## Overview
 
-API for communication suppliers to integrate with NHS Notify.
+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
@@ -9,23 +16,21 @@ Use this API to retrieve letters to be printed
 
 ## Who can use this API
 
-The NHS Notify Supplier service is intended for suppliers of print services to the [NHS Notify](https://digital.nhs.uk/services/nhs-notify) service
+ 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 development](https://digital.nhs.uk/developer/guides-and-documentation/reference-guide#statuses) meaning:
+This API is [in production, beta](https://digital.nhs.uk/developer/guides-and-documentation/reference-guide#statuses). We are onboarding partners to use it.
 
-* it is available for testing in the integration environment
-* we expect to make breaking changes based on developer feedback
+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
 
-TBD
-
+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
@@ -36,9 +41,20 @@ We follow the [JSON:API](https://jsonapi.org/) standard for our request and resp
 
 ### Response content types
 
-This API can generate responses in the following formats:
+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
 
@@ -60,9 +76,9 @@ To access this API, use the following security pattern:
 
 | Environment | Base URL |
 |------------ | -------- |
-| Sandbox     | `https://sandbox.api.service.nhs.uk/comms` |
-| Integration test | `https://int.api.service.nhs.uk/comms` |
-| Production | `https://api.service.nhs.uk/comms` |
+| 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
 
@@ -75,6 +91,10 @@ Our [sandbox environment](https://digital.nhs.uk/developer/guides-and-documentat
 
 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:
@@ -86,3 +106,15 @@ Our integration test environment:
 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

specification/api/components/documentation/createMI.md

@@ -1,8 +1,8 @@
 ## Overview
 
-Submit a Management Information (MI) record for your activity (counts and costs for letters).
+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 created(201) response code along with the created data including a unique id for the record or an unsuccessful (4xx/%xx) response
+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
 

specification/api/components/documentation/getDataId.md

@@ -1,6 +1,6 @@
 ## Overview
 
-Download the data file for a letter via a redirect to a signed URL.
+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
 

specification/api/components/documentation/getLetterStatus.md

@@ -1,6 +1,6 @@
 ## Overview
 
-Get the current status of a single letter by its ID.
+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
 

specification/api/components/documentation/headDataId.md

@@ -1,6 +1,6 @@
 ## Overview
 
-Check whether a data file exists for a letter without downloading it.
+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
 

specification/api/components/documentation/listLetters.md

@@ -1,6 +1,6 @@
 ## Overview
 
-Get a LIST of **PENDING** letters that are ready to print .
+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).

specification/api/components/documentation/patchLetter.md

@@ -1,6 +1,6 @@
 ## Overview
 
-Update the status of a single letter by its ID, optionally providing a reason code and text.
+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.
 

specification/api/components/documentation/postLetters.md

@@ -1,6 +1,8 @@
 ## Overview
 
-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 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.
 

specification/api/notify-supplier-phase1.yml

@@ -62,12 +62,12 @@ tags:
   - name: data
     description: ''
 servers:
+  - url: 'https://internal-dev-sandbox.api.service.nhs.uk/nhs-notify-supplier'
+    description: Public sandbox
   - url: 'http://127.0.0.1:9000'
     description: Local development server
-  - url: 'https://sandbox-server.nhs.uk/nhs-notify-supplier-api'
-    description: Public sandbox
 x-nhsd-apim:
-  temporary: true
+  temporary: false
   monitoring: false
   access:
     $ref: ./components/x-nhsd-apim/access.yml