Updated reason code to string

nhsd-david-wass · nhsd-david-wass · commit 0375c3ef0d66 · 2025-10-16T08:53:03.000+01:00
diff --git 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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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/specification/api/components/documentation/createMI.md b/specification/api/components/documentation/createMI.md
@@ -1,3 +1,17 @@
 ## Overview
 
-Use this endpoint to create management information
+Submit a Management Information (MI) record for your activity (counts and costs for letters).
+
+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
+
+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
@@ -1,3 +1,14 @@
 ## Overview
 
-Use this endpoint to get letter data
+Download the data file for a letter via a redirect to a signed URL.
+
+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
@@ -1,6 +1,8 @@
 ## Overview
 
-Use this endpoint to get details the status of a letter.
+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
 
diff --git a/specification/api/components/documentation/headDataId.md b/specification/api/components/documentation/headDataId.md
@@ -1,3 +1,12 @@
 ## Overview
 
-Use this endpoint to check for the existence of letter data
+Check whether a data file exists for a letter without downloading it.
+
+## 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
@@ -1,3 +1,8 @@
 ## Overview
 
-The key use of this endpoint is to query letters which are ready to be printed
+Get a LIST of **PENDING** letters that are ready to print .
+
+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
@@ -0,0 +1,27 @@
+## Overview
+
+Update the status of a single letter by its ID, 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/patchLetters.md b/specification/api/components/documentation/patchLetters.md
diff --git a/specification/api/components/documentation/postLetters.md b/specification/api/components/documentation/postLetters.md
@@ -1,3 +1,27 @@
 ## Overview
 
-Update the status of multiple letters by providing the new statuses in the request body.
+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.
+
+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
@@ -9,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/patchLetter.yml b/specification/api/components/endpoints/patchLetter.yml
@@ -1,8 +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/patchLetters.md'
+  $ref: '../documentation/patchLetter.md'
 requestBody:
   $ref: "../requests/patchLetterRequest.yml"
 responses:
diff --git 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
@@ -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
@@ -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
@@ -0,0 +1,3 @@
+type: string
+description: Reason text for the given status
+example: failed validation

Original file line number	Diff line number	Diff line change
`@@ -1,7 +1,7 @@`
`1`	`1`	`{`
`2`	`2`	`"data": {`
`3`	`3`	`"attributes": {`
`4`		`- "reasonCode": 100,`
	`4`	`+ "reasonCode": "R01",`
`5`	`5`	`"reasonText": "failed validation",`
`6`	`6`	`"status": "CANCELLED"`
`7`	`7`	`},`