diff --git a/.github/actions/build-sdk/action.yml b/.github/actions/build-sdk/action.yml
index 95da5b22f..0443d76c6 100644
--- a/.github/actions/build-sdk/action.yml
+++ b/.github/actions/build-sdk/action.yml
@@ -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
diff --git a/sandbox/data/examples/getLetter/responses/getLetter-2WL5eYSWGzCHlGmzNxuqVusPxDg.json b/sandbox/data/examples/getLetter/responses/getLetter-2WL5eYSWGzCHlGmzNxuqVusPxDg.json
index c0b542175..ec685a98b 100644
--- a/sandbox/data/examples/getLetter/responses/getLetter-2WL5eYSWGzCHlGmzNxuqVusPxDg.json
+++ b/sandbox/data/examples/getLetter/responses/getLetter-2WL5eYSWGzCHlGmzNxuqVusPxDg.json
@@ -2,7 +2,7 @@
   "data": {
     "attributes": {
       "groupId": "c5d93f917f5546d08beccf770a915d96",
-      "reasonCode": 100,
+      "reasonCode": "R01",
       "reasonText": "failed validation",
       "specificationId": "2WL5eYSWGzCHlGmzNxuqVusPxDg",
       "status": "REJECTED"
diff --git a/sandbox/data/examples/getLetter/responses/getLetter-2XL5eYSWGzCHlGmzNxuqVusPxDg.json b/sandbox/data/examples/getLetter/responses/getLetter-2XL5eYSWGzCHlGmzNxuqVusPxDg.json
index ff627ba76..d37729d62 100644
--- a/sandbox/data/examples/getLetter/responses/getLetter-2XL5eYSWGzCHlGmzNxuqVusPxDg.json
+++ b/sandbox/data/examples/getLetter/responses/getLetter-2XL5eYSWGzCHlGmzNxuqVusPxDg.json
@@ -2,7 +2,7 @@
   "data": {
     "attributes": {
       "groupId": "c5d93f917f5546d08beccf770a915d96",
-      "reasonCode": 100,
+      "reasonCode": "R01",
       "specificationId": "2WL5eYSWGzCHlGmzNxuqVusPxDg",
       "status": "CANCELLED"
     },
diff --git a/sandbox/data/examples/getLetter/responses/getLetter-2YL5eYSWGzCHlGmzNxuqVusPxDg.json b/sandbox/data/examples/getLetter/responses/getLetter-2YL5eYSWGzCHlGmzNxuqVusPxDg.json
index d9112401d..945e8270b 100644
--- a/sandbox/data/examples/getLetter/responses/getLetter-2YL5eYSWGzCHlGmzNxuqVusPxDg.json
+++ b/sandbox/data/examples/getLetter/responses/getLetter-2YL5eYSWGzCHlGmzNxuqVusPxDg.json
@@ -2,7 +2,7 @@
   "data": {
     "attributes": {
       "groupId": "c5d93f917f5546d08beccf770a915d96",
-      "reasonCode": 100,
+      "reasonCode": "R01",
       "reasonText": "failed validation",
       "specificationId": "2WL5eYSWGzCHlGmzNxuqVusPxDg",
       "status": "FAILED"
diff --git a/sandbox/data/examples/getLetter/responses/getLetter-2ZL5eYSWGzCHlGmzNxuqVusPxDg.json b/sandbox/data/examples/getLetter/responses/getLetter-2ZL5eYSWGzCHlGmzNxuqVusPxDg.json
index 7e471a474..fff8bf1dd 100644
--- a/sandbox/data/examples/getLetter/responses/getLetter-2ZL5eYSWGzCHlGmzNxuqVusPxDg.json
+++ b/sandbox/data/examples/getLetter/responses/getLetter-2ZL5eYSWGzCHlGmzNxuqVusPxDg.json
@@ -2,7 +2,7 @@
   "data": {
     "attributes": {
       "groupId": "c5d93f917f5546d08beccf770a915d96",
-      "reasonCode": 100,
+      "reasonCode": "R01",
       "reasonText": "failed validation",
       "specificationId": "2WL5eYSWGzCHlGmzNxuqVusPxDg",
       "status": "RETURNED"
diff --git a/sandbox/data/examples/patchLetter/requests/patchLetter_CANCELLED.json b/sandbox/data/examples/patchLetter/requests/patchLetter_CANCELLED.json
index fd6e5e9ff..7106a2f53 100644
--- a/sandbox/data/examples/patchLetter/requests/patchLetter_CANCELLED.json
+++ b/sandbox/data/examples/patchLetter/requests/patchLetter_CANCELLED.json
@@ -1,7 +1,7 @@
 {
   "data": {
     "attributes": {
-      "reasonCode": 100,
+      "reasonCode": "R01",
       "reasonText": "failed validation",
       "status": "CANCELLED"
     },
diff --git a/sandbox/data/examples/patchLetter/requests/patchLetter_FAILED.json b/sandbox/data/examples/patchLetter/requests/patchLetter_FAILED.json
index 4398da84b..359d9bc3d 100644
--- a/sandbox/data/examples/patchLetter/requests/patchLetter_FAILED.json
+++ b/sandbox/data/examples/patchLetter/requests/patchLetter_FAILED.json
@@ -1,7 +1,7 @@
 {
   "data": {
     "attributes": {
-      "reasonCode": 100,
+      "reasonCode": "R01",
       "reasonText": "failed validation",
       "status": "FAILED"
     },
diff --git a/sandbox/data/examples/patchLetter/requests/patchLetter_REJECTED.json b/sandbox/data/examples/patchLetter/requests/patchLetter_REJECTED.json
index 5b54d3fb7..c44c0558e 100644
--- a/sandbox/data/examples/patchLetter/requests/patchLetter_REJECTED.json
+++ b/sandbox/data/examples/patchLetter/requests/patchLetter_REJECTED.json
@@ -1,7 +1,7 @@
 {
   "data": {
     "attributes": {
-      "reasonCode": 100,
+      "reasonCode": "R01",
       "reasonText": "failed validation",
       "status": "REJECTED"
     },
diff --git a/sandbox/data/examples/patchLetter/requests/patchLetter_RETURNED.json b/sandbox/data/examples/patchLetter/requests/patchLetter_RETURNED.json
index 5b54d3fb7..c44c0558e 100644
--- a/sandbox/data/examples/patchLetter/requests/patchLetter_RETURNED.json
+++ b/sandbox/data/examples/patchLetter/requests/patchLetter_RETURNED.json
@@ -1,7 +1,7 @@
 {
   "data": {
     "attributes": {
-      "reasonCode": 100,
+      "reasonCode": "R01",
       "reasonText": "failed validation",
       "status": "REJECTED"
     },
diff --git a/sandbox/data/examples/patchLetter/responses/patchLetter_CANCELLED.json b/sandbox/data/examples/patchLetter/responses/patchLetter_CANCELLED.json
index c73ad66b5..a05095196 100644
--- a/sandbox/data/examples/patchLetter/responses/patchLetter_CANCELLED.json
+++ b/sandbox/data/examples/patchLetter/responses/patchLetter_CANCELLED.json
@@ -1,7 +1,7 @@
 {
   "data": {
     "attributes": {
-      "reasonCode": 100,
+      "reasonCode": "R01",
       "reasonText": "failed validation",
       "specificationId": "2WL5eYSWGzCHlGmzNxuqVusPxDg",
       "status": "CANCELLED"
diff --git a/sandbox/data/examples/patchLetter/responses/patchLetter_FAILED.json b/sandbox/data/examples/patchLetter/responses/patchLetter_FAILED.json
index c5b2c5a96..b2c2f9025 100644
--- a/sandbox/data/examples/patchLetter/responses/patchLetter_FAILED.json
+++ b/sandbox/data/examples/patchLetter/responses/patchLetter_FAILED.json
@@ -1,7 +1,7 @@
 {
   "data": {
     "attributes": {
-      "reasonCode": 100,
+      "reasonCode": "R01",
       "reasonText": "failed validation",
       "specificationId": "2WL5eYSWGzCHlGmzNxuqVusPxDg",
       "status": "FAILED"
diff --git a/sandbox/data/examples/patchLetter/responses/patchLetter_REJECTED.json b/sandbox/data/examples/patchLetter/responses/patchLetter_REJECTED.json
index 706b8df85..98a205e55 100644
--- a/sandbox/data/examples/patchLetter/responses/patchLetter_REJECTED.json
+++ b/sandbox/data/examples/patchLetter/responses/patchLetter_REJECTED.json
@@ -1,7 +1,7 @@
 {
   "data": {
     "attributes": {
-      "reasonCode": 100,
+      "reasonCode": "R01",
       "reasonText": "failed validation",
       "specificationId": "2WL5eYSWGzCHlGmzNxuqVusPxDg",
       "status": "REJECTED"
diff --git a/sandbox/data/examples/patchLetter/responses/patchLetter_RETURNED.json b/sandbox/data/examples/patchLetter/responses/patchLetter_RETURNED.json
index 0c80fcc58..eb3a70a07 100644
--- a/sandbox/data/examples/patchLetter/responses/patchLetter_RETURNED.json
+++ b/sandbox/data/examples/patchLetter/responses/patchLetter_RETURNED.json
@@ -1,7 +1,7 @@
 {
   "data": {
     "attributes": {
-      "reasonCode": 100,
+      "reasonCode": "R01",
       "reasonText": "failed validation",
       "specificationId": "2WL5eYSWGzCHlGmzNxuqVusPxDg",
       "status": "RETURNED"
diff --git a/sandbox/data/examples/postLetter/requests/postLetters.json b/sandbox/data/examples/postLetter/requests/postLetters.json
index c5d605981..1b42413dc 100644
--- a/sandbox/data/examples/postLetter/requests/postLetters.json
+++ b/sandbox/data/examples/postLetter/requests/postLetters.json
@@ -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"
       },
diff --git a/scripts/config/markdownlint.yaml b/scripts/config/markdownlint.yaml
index 554ab554b..9f92b8daf 100644
--- a/scripts/config/markdownlint.yaml
+++ b/scripts/config/markdownlint.yaml
@@ -9,3 +9,6 @@ MD024:
 
 # https://github.com/DavidAnson/markdownlint/blob/main/doc/md033.md
 MD033: false
+
+MD041:
+  level: 2
diff --git a/scripts/config/vale/styles/config/vocabularies/words/accept.txt b/scripts/config/vale/styles/config/vocabularies/words/accept.txt
index df23489fc..cf5b436d2 100644
--- a/scripts/config/vale/styles/config/vocabularies/words/accept.txt
+++ b/scripts/config/vale/styles/config/vocabularies/words/accept.txt
@@ -20,7 +20,7 @@ Jira
 Makefile
 OAuth
 Octokit
-onboarding
+[Oo]nboarding
 Podman
 pre
 Python
diff --git a/specification/api/components/documentation/APIDescription.md b/specification/api/components/documentation/APIDescription.md
new file mode 100644
index 000000000..9a2db4488
--- /dev/null
+++ b/specification/api/components/documentation/APIDescription.md
@@ -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
diff --git a/specification/api/components/documentation/createMI.md b/specification/api/components/documentation/createMI.md
new file mode 100644
index 000000000..17aff50ee
--- /dev/null
+++ b/specification/api/components/documentation/createMI.md
@@ -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|
diff --git a/specification/api/components/documentation/getDataId.md b/specification/api/components/documentation/getDataId.md
new file mode 100644
index 000000000..81e742e15
--- /dev/null
+++ b/specification/api/components/documentation/getDataId.md
@@ -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 |
diff --git a/specification/api/components/documentation/getLetterStatus.md b/specification/api/components/documentation/getLetterStatus.md
new file mode 100644
index 000000000..257d4d7d2
--- /dev/null
+++ b/specification/api/components/documentation/getLetterStatus.md
@@ -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`|
diff --git a/specification/api/components/documentation/headDataId.md b/specification/api/components/documentation/headDataId.md
new file mode 100644
index 000000000..66e98407f
--- /dev/null
+++ b/specification/api/components/documentation/headDataId.md
@@ -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) |
diff --git a/specification/api/components/documentation/listLetters.md b/specification/api/components/documentation/listLetters.md
new file mode 100644
index 000000000..337033c73
--- /dev/null
+++ b/specification/api/components/documentation/listLetters.md
@@ -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
diff --git a/specification/api/components/documentation/patchLetter.md b/specification/api/components/documentation/patchLetter.md
new file mode 100644
index 000000000..f577051e2
--- /dev/null
+++ b/specification/api/components/documentation/patchLetter.md
@@ -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.
diff --git a/specification/api/components/documentation/postLetters.md b/specification/api/components/documentation/postLetters.md
new file mode 100644
index 000000000..b2ebee69d
--- /dev/null
+++ b/specification/api/components/documentation/postLetters.md
@@ -0,0 +1,29 @@
+## 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.
diff --git a/specification/api/components/endpoints/createMI.yml b/specification/api/components/endpoints/createMI.yml
index edfead9b7..09d0ebce6 100644
--- a/specification/api/components/endpoints/createMI.yml
+++ b/specification/api/components/endpoints/createMI.yml
@@ -1,4 +1,6 @@
 summary: Create a new MI record
+description:
+  $ref: '../documentation/createMI.md'
 operationId: createMI
 tags:
   - mi
@@ -7,6 +9,8 @@ requestBody:
 responses:
   '201':
     $ref: "../responses/postMI201.yml"
+  '400':
+    $ref: "../responses/errors/badRequest.yml"
   '404':
     $ref: "../responses/errors/resourceNotFound.yml"
   '429':
diff --git a/specification/api/components/endpoints/getDataId.yml b/specification/api/components/endpoints/getDataId.yml
index db949b23e..c7574df40 100644
--- a/specification/api/components/endpoints/getDataId.yml
+++ b/specification/api/components/endpoints/getDataId.yml
@@ -1,4 +1,6 @@
 summary: Fetch a data file
+description:
+  $ref: '../documentation/getDataId.md'
 operationId: getDataId
 tags:
   - data
diff --git a/specification/api/components/endpoints/getLetterStatus.yml b/specification/api/components/endpoints/getLetterStatus.yml
index eed23ab02..bee57b469 100644
--- a/specification/api/components/endpoints/getLetterStatus.yml
+++ b/specification/api/components/endpoints/getLetterStatus.yml
@@ -1,22 +1,6 @@
 summary: Retrieve the status of a letter
-description: |
-  ## Get details the status of a letter.
-
-  ## 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`|
+description:
+  $ref: '../documentation/getLetterStatus.md'
 operationId: getLetterStatus
 responses:
   "200":
diff --git a/specification/api/components/endpoints/headDataId.yml b/specification/api/components/endpoints/headDataId.yml
index 7c09cf5e1..ce692737c 100644
--- a/specification/api/components/endpoints/headDataId.yml
+++ b/specification/api/components/endpoints/headDataId.yml
@@ -1,4 +1,6 @@
 summary: Check for the existence of a data file
+description:
+  $ref: '../documentation/headDataId.md'
 tags:
   - data
 responses:
diff --git a/specification/api/components/endpoints/listLetters.yml b/specification/api/components/endpoints/listLetters.yml
index 9d5898c8d..ab877e52f 100644
--- a/specification/api/components/endpoints/listLetters.yml
+++ b/specification/api/components/endpoints/listLetters.yml
@@ -7,7 +7,8 @@ parameters:
 #  - $ref: "../parameters/letterStatus.yml"
 #  - $ref: "../parameters/pageNumber.yml"
   - $ref: "../parameters/limit.yml"
-description: The key use of this endpoint is to query letters which are ready to be printed
+description:
+  $ref: '../documentation/listLetters.md'
 responses:
   '200':
     $ref: "../responses/getLetters200.yml"
diff --git a/specification/api/components/endpoints/patchLetter.yml b/specification/api/components/endpoints/patchLetter.yml
index 411d1b64e..a6e9cff5f 100644
--- a/specification/api/components/endpoints/patchLetter.yml
+++ b/specification/api/components/endpoints/patchLetter.yml
@@ -1,6 +1,7 @@
 summary: Update the status of a letter
-description: Update the status of a letter by providing the new status in the request body.
 operationId: patchLetter
+description:
+  $ref: '../documentation/patchLetter.md'
 requestBody:
   $ref: "../requests/patchLetterRequest.yml"
 responses:
diff --git a/specification/api/components/endpoints/postLetters.yml b/specification/api/components/endpoints/postLetters.yml
index b49fd2d44..54c5fabaf 100644
--- a/specification/api/components/endpoints/postLetters.yml
+++ b/specification/api/components/endpoints/postLetters.yml
@@ -1,4 +1,6 @@
 summary: Update the status of multiple letters
+description:
+  $ref: '../documentation/postLetters.md'
 operationId: postLetters
 tags:
   - letter
diff --git a/specification/api/components/schemas/letterItem.yml b/specification/api/components/schemas/letterItem.yml
index ee6d53187..a62bd6fdb 100644
--- a/specification/api/components/schemas/letterItem.yml
+++ b/specification/api/components/schemas/letterItem.yml
@@ -21,10 +21,6 @@ properties:
       status:
         $ref: "./letterStatus.yml"
       reasonCode:
-        type: number
-        description: Reason code for the given status
-        example: 100
+        $ref: "./reasonCode.yml"
       reasonText:
-        type: string
-        description: Reason text for the given status
-        example: failed validation
+        $ref: "./reasonText.yml"
diff --git a/specification/api/components/schemas/letterUpdateItem.yml b/specification/api/components/schemas/letterUpdateItem.yml
index ea23bbb44..f85545411 100644
--- a/specification/api/components/schemas/letterUpdateItem.yml
+++ b/specification/api/components/schemas/letterUpdateItem.yml
@@ -18,10 +18,6 @@ properties:
       status:
         $ref: "./letterStatus.yml"
       reasonCode:
-        type: number
-        description: Reason code for the given status
-        example: 100
+        $ref: "./reasonCode.yml"
       reasonText:
-        type: string
-        description: Reason text for the given status
-        example: failed validation
+        $ref: "./reasonText.yml"
diff --git a/specification/api/components/schemas/reasonCode.yml b/specification/api/components/schemas/reasonCode.yml
new file mode 100644
index 000000000..2ed2fcff3
--- /dev/null
+++ b/specification/api/components/schemas/reasonCode.yml
@@ -0,0 +1,3 @@
+type: string
+description: Reason code for the given status
+example: "R01"
diff --git a/specification/api/components/schemas/reasonText.yml b/specification/api/components/schemas/reasonText.yml
new file mode 100644
index 000000000..796f633be
--- /dev/null
+++ b/specification/api/components/schemas/reasonText.yml
@@ -0,0 +1,3 @@
+type: string
+description: Reason text for the given status
+example: failed validation
diff --git a/specification/api/components/security/security-int.yml b/specification/api/components/security/security-int.yml
new file mode 100644
index 000000000..878d7f275
--- /dev/null
+++ b/specification/api/components/security/security-int.yml
@@ -0,0 +1 @@
+app-level3: [ ]
diff --git a/specification/api/components/security/security-prod.yml b/specification/api/components/security/security-prod.yml
new file mode 100644
index 000000000..878d7f275
--- /dev/null
+++ b/specification/api/components/security/security-prod.yml
@@ -0,0 +1 @@
+app-level3: [ ]
diff --git a/specification/api/components/security/security-ref.yml b/specification/api/components/security/security-ref.yml
new file mode 100644
index 000000000..878d7f275
--- /dev/null
+++ b/specification/api/components/security/security-ref.yml
@@ -0,0 +1 @@
+app-level3: [ ]
diff --git a/specification/api/components/security/security.yml b/specification/api/components/security/security.yml
index 58151922d..393524ce3 100644
--- a/specification/api/components/security/security.yml
+++ b/specification/api/components/security/security.yml
@@ -1 +1 @@
-$ref: security-sandbox.yml
+$ref: security-prod.yml
diff --git a/specification/api/components/x-nhsd-apim/access-int.yml b/specification/api/components/x-nhsd-apim/access-int.yml
new file mode 100644
index 000000000..de21d5dc5
--- /dev/null
+++ b/specification/api/components/x-nhsd-apim/access-int.yml
@@ -0,0 +1,3 @@
+- title: Application Restricted
+  grants:
+    app-level3: []
diff --git a/specification/api/components/x-nhsd-apim/access-prod.yml b/specification/api/components/x-nhsd-apim/access-prod.yml
new file mode 100644
index 000000000..de21d5dc5
--- /dev/null
+++ b/specification/api/components/x-nhsd-apim/access-prod.yml
@@ -0,0 +1,3 @@
+- title: Application Restricted
+  grants:
+    app-level3: []
diff --git a/specification/api/components/x-nhsd-apim/access-ref.yml b/specification/api/components/x-nhsd-apim/access-ref.yml
new file mode 100644
index 000000000..de21d5dc5
--- /dev/null
+++ b/specification/api/components/x-nhsd-apim/access-ref.yml
@@ -0,0 +1,3 @@
+- title: Application Restricted
+  grants:
+    app-level3: []
diff --git a/specification/api/components/x-nhsd-apim/access.yml b/specification/api/components/x-nhsd-apim/access.yml
index 95f5f0b94..c69c222d1 100644
--- a/specification/api/components/x-nhsd-apim/access.yml
+++ b/specification/api/components/x-nhsd-apim/access.yml
@@ -1 +1 @@
-$ref: access-sandbox.yml
+$ref: access-prod.yml
diff --git a/specification/api/components/x-nhsd-apim/target-int.yml b/specification/api/components/x-nhsd-apim/target-int.yml
new file mode 100644
index 000000000..040d1228c
--- /dev/null
+++ b/specification/api/components/x-nhsd-apim/target-int.yml
@@ -0,0 +1,6 @@
+type: external
+healthcheck: /_status
+url: https://suppliers.int.nhsnotify.national.nhs.uk
+security:
+  type: mtls
+  secret: nhs-notify-supplier-mtls-int
diff --git a/specification/api/components/x-nhsd-apim/target-prod.yml b/specification/api/components/x-nhsd-apim/target-prod.yml
new file mode 100644
index 000000000..70f523ca2
--- /dev/null
+++ b/specification/api/components/x-nhsd-apim/target-prod.yml
@@ -0,0 +1,6 @@
+type: external
+healthcheck: /_status
+url: https://suppliers.prod.nhsnotify.national.nhs.uk
+security:
+  type: mtls
+  secret: nhs-notify-supplier-mtls-prod
diff --git a/specification/api/components/x-nhsd-apim/target-ref.yml b/specification/api/components/x-nhsd-apim/target-ref.yml
new file mode 100644
index 000000000..8ace3f78e
--- /dev/null
+++ b/specification/api/components/x-nhsd-apim/target-ref.yml
@@ -0,0 +1,6 @@
+type: external
+healthcheck: /_status
+url: https://suppliers.ref.nhsnotify.national.nhs.uk
+security:
+  type: mtls
+  secret: nhs-notify-supplier-mtls-ref
diff --git a/specification/api/components/x-nhsd-apim/target.yml b/specification/api/components/x-nhsd-apim/target.yml
index b24b21da4..a0f578ca7 100644
--- a/specification/api/components/x-nhsd-apim/target.yml
+++ b/specification/api/components/x-nhsd-apim/target.yml
@@ -1 +1 @@
-$ref: target-sandbox.yml
+$ref: target-prod.yml
diff --git a/specification/api/notify-supplier-phase1.yml b/specification/api/notify-supplier-phase1.yml
index 4a588b025..bccf356ef 100644
--- a/specification/api/notify-supplier-phase1.yml
+++ b/specification/api/notify-supplier-phase1.yml
@@ -2,11 +2,8 @@ openapi: 3.0.3
 info:
   version: next
   title: NHS Notify Supplier API
-  description: |
-    API for communication suppliers to integrate with NHS Notify.
-
-    This specification represents the in-development 'next' version of the API schema
-    and should be treated as unstable.
+  description:
+    $ref: 'components/documentation/APIDescription.md'
 security:
   - $ref: 'components/security/security.yml'
 paths:
@@ -65,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