diff --git a/.markdownlint.jsonc b/.markdownlint.jsonc
index a2672f790..93ec2c05f 100644
--- a/.markdownlint.jsonc
+++ b/.markdownlint.jsonc
@@ -7,5 +7,6 @@
"siblings_only": true
},
// https://github.com/DavidAnson/markdownlint/blob/main/doc/md033.md
- "MD033": false
+ "MD033": false,
+ "MD041": false
}
diff --git a/VERSION b/VERSION
index 6a1200d76..0aec44bc0 100644
--- a/VERSION
+++ b/VERSION
@@ -1 +1 @@
-1.3.0-${yyyy}${mm}${dd}.${HH}${MM}${SS}+${hash}
+1.3.1-${yyyy}${mm}${dd}.${HH}${MM}${SS}+${hash}
diff --git a/specification/.markdownlint.json b/specification/.markdownlint.json
deleted file mode 100644
index d4221b279..000000000
--- a/specification/.markdownlint.json
+++ /dev/null
@@ -1,6 +0,0 @@
-{
- "MD041": {
- "level": 2
- },
- "extends": "../.markdownlint.jsonc"
-}
diff --git a/specification/api/components/documentation/patchLetter.md b/specification/api/components/documentation/patchLetter.md
index e29b229d5..2eb45db69 100644
--- a/specification/api/components/documentation/patchLetter.md
+++ b/specification/api/components/documentation/patchLetter.md
@@ -23,11 +23,19 @@ Allowed `status` values that can be used to are:
It is not possible to update a letter to status of `PENDING`.
+### Reason Codes
+
Optionally a `reasonCode` and `reasonText` explaining the status (for example, validation failures) can be included in the request body.
-### Example Error Codes
+With the exception of the `RETURNED` status, `reasonCode` and `reasonText` can be agreed on an individual basis
+
+#### RETURNED Updates
+
+NHS Notify uses a standardised set of reasons for the `RETURNED` status.
+
+Both a `reasonCode` and `reasonText` must be provided for a `RETURNED` status update.
-Examples of reason codes and text that may be returned include (but are not limited to)
+The reason codes and expected text for the `RETURNED` status are as follows:
| Reason Code | Reason Text |
|-------------|----------------------------|
diff --git a/specification/api/components/documentation/postLetters.md b/specification/api/components/documentation/postLetters.md
index e1b2b1273..298e68f96 100644
--- a/specification/api/components/documentation/postLetters.md
+++ b/specification/api/components/documentation/postLetters.md
@@ -29,9 +29,15 @@ The request should not contain multiple letter objects with the same ID.
Optionally a `reasonCode` and `reasonText` explaining the status (for example, validation failures) can be included in the request body for each update.
-### Example Error Codes
+With the exception of the `RETURNED` status, `reasonCode` and `reasonText` can be agreed on an individual basis based on supplier workflows.
-Examples of reason codes and text that may be returned include (but are not limited to)
+#### RETURNED Updates
+
+NHS Notify uses a standardised set of reasons for the `RETURNED` status.
+
+Both a `reasonCode` and `reasonText` must be provided for a `RETURNED` status update.
+
+The reason codes and expected text for the `RETURNED` status are as follows:
| Reason Code | Reason Text |
|-------------|----------------------------|