{"openapi":"3.0.3","info":{"title":"NHS Notify Supplier API","description":"## Overview\n\nUse this API to retrieve letters to be printed.\n\nThis API lets you:\n\n* get lists of letters allocated to you\n* download letter PDFs and metadata\n* update and manage letter statuses\n* submit and retrieve management information (MI)\n\nThis specification represents the in-development 'next' version of the API schema\nand should be treated as unstable.\n\n## Who can use this API\n\nThe 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.\n\n## Access Modes\n\nThis API has one access mode. It is:\n\n* restricted access\n\n### Restricted access\n\nThis access mode is [application-restricted](https://digital.nhs.uk/developer/guides-and-documentation/security-and-authorisation#application-restricted-apis), meaning we authenticate and authorise the calling application but not the end user.\n\nAuthentication and authorisation of end users is the responsibility of your application.\n\nTo use this access mode, use this security pattern:\n\n* [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)\n\n## API status and roadmap\n\nThis API is [in production, beta](https://digital.nhs.uk/developer/guides-and-documentation/reference-guide#statuses). We are onboarding partners to use it.\n\nWe 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.\n\n## Service level\n\nThis 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.\nFor more details, see [service levels](https://digital.nhs.uk/developer/guides-and-documentation/reference-guide#service-levels).\n\n## Rate limits\n\nThe default rate limit is 300TPS (Transactions Per Second), per app. If you require a higher rate limit please [contact us](https://digital.nhs.uk/developer/help-and-support). or raise this during the onboarding process.\n\n## Technology\n\nThis API is a [REST-based](https://digital.nhs.uk/developer/guides-and-documentation/our-api-technologies#basic-rest) API.\n\nWe follow the [JSON:API](https://jsonapi.org/) standard for our request and response schemas.\n\n### Response content types\n\nThis API can generate responses in the following format:\n\n* `application/vnd.api+json` - see [JSON:API specification](https://jsonapi.org/format/#introduction)\n\n### Request content types\n\nThis API will accept request payloads of the following types:\n\n* `application/vnd.api+json` - see [JSON:API specification](https://jsonapi.org/format/#introduction)\n* `application/json`\n\nThe `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.\n\nIf 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.\n\n## Network access\n\nThis 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).\n\nFor more details see [Network access for APIs](https://digital.nhs.uk/developer/guides-and-documentation/network-access-for-apis).\n\n## Errors\n\nWe use standard HTTP status codes to show whether an API request succeeded or not. They are usually in the range:\n\n* 200 to 299 if it succeeded, including code 202 if it was accepted by an API that needs to wait for further action\n* 400 to 499 if it failed because of a client error by your application\n* 500 to 599 if it failed because of an error on our server\n\nErrors specific to each API are shown in the Endpoints section, under Response. See our [reference guide](https://digital.nhs.uk/developer/guides-and-documentation/reference-guide#http-status-codes) for more on errors.\n\nYour API-calling application should have a mechanism to automatically try again, for example by giving status information to your end user, before giving up. See our [reference guide](https://digital.nhs.uk/developer/guides-and-documentation/reference-guide#error-handling) for more information about error handling.\n\n## Open source\n\nYou might find the following [open source](https://digital.nhs.uk/developer/guides-and-documentation/reference-guide#open-source) resources useful:\n\n| Resource                  | Description                                                          | Links                                                                          |\n|---------------------------|----------------------------------------------------------------------|--------------------------------------------------------------------------------|\n| Notify Supplier API       | Source code for the API proxy, sandbox and specification.            | [GitHub repo](https://github.com/NHSDigital/notify-supplier-api) |\n\n## Environments and testing\n\n| Environment | Base URL |\n|------------ | -------- |\n| Sandbox     | `https://sandbox.api.service.nhs.uk/nhs-notify-supplier` |\n| Integration test | `https://int.api.service.nhs.uk/nhs-notify-supplier` |\n| Production | `https://api.service.nhs.uk/nhs-notify-supplier` |\n\n### Sandbox testing\n\nOur [sandbox environment](https://digital.nhs.uk/developer/guides-and-documentation/testing#sandbox-testing):\n\n* is for early developer testing\n* only covers a limited set of scenarios\n* is stateless, so does not actually persist any updates\n* is open access, so does not allow you to test authorisation\n\nFor details of sandbox test scenarios, or to try out sandbox using our 'Try this API' feature, see the documentation for each endpoint.\n\nAlternatively, you can try out the sandbox using our Postman collection.\n\nYou can find our postman collection source in our [public repository on github](https://github.com/NHSDigital/nhs-notify-supplier-api/tree/main/postman).\n\n### Integration testing\n\nOur integration test environment:\n\n* is for formal integration sandbox-testing\n* is stateful, so persists updates\n* includes authorisation via [signed JWT authentication](https://digital.nhs.uk/developer/guides-and-documentation/security-and-authorisation/application-restricted-restful-apis-signed-jwt-authentication)\n\nYou need to get your software approved by us before it can go live with this API.\n\n### Production smoke testing\n\nBefore go-live, you must complete a smoke test in the NHS Notify production environment.\nThe 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.\n\nThe process is as follows:\n\n* retrieve and print one or more live test letters through the production API.\n* send the printed output to the address provided.\n* submit a Management Information (MI) update for verification.\n\nThe NHS Notify team will configure your production access, review your results, and confirm that your output meets NHS Notify print specifications.\n\n## Onboarding\n\nYou need to get your software approved by us before it can go live with this API.\nYou will also need to be an approved NHS letter supplier under the framework agreement and nominate your technical and operational contacts.\n\n## Related APIs\n\nThe [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.\n\n## Contact us\n\nFor help and support connecting to our APIs and to join our developer community, see [Help and support building healthcare software](https://digital.nhs.uk/developer/help-and-support).\n","version":"next"},"servers":[{"url":"https://sandbox.api.service.nhs.uk/nhs-notify-supplier","description":"Public sandbox"},{"url":"http://127.0.0.1:9000","description":"Local development server"}],"paths":{"/letters":{"get":{"tags":["letter"],"summary":"Get a list of PENDING letters","description":"## Overview\n\nUse this endpoint to poll letters which are ready to be printed.\n\nReturns letters whose `status` is **PENDING**.\nUse `limit` to control list size (max 2500).\n\nRate limiting applies. On excess requests, you may receive **429 Too Many Requests** (example error code(s): `NOTIFY_QUOTA`). Back off and retry later.\n","operationId":"listLetters","parameters":[{"name":"limit","in":"query","description":"The maximum number of items to return in a single request, max 2500","required":false,"deprecated":false,"allowEmptyValue":false,"explode":false,"allowReserved":false,"schema":{"type":"number","example":2500}}],"responses":{"200":{"description":"List of letters to process","headers":{"X-Request-ID":{"name":"","in":"header","description":"Unique request identifier, in the format of a GUID\n","required":false,"deprecated":false,"allowEmptyValue":false,"explode":false,"allowReserved":false,"schema":{"type":"string","example":"dcb9c8dc-c2f4-4d5f-8674-a2e913e040b2"}},"X-Correlation-ID":{"name":"","in":"header","description":"An optional ID which you can use to track transactions across multiple systems. It can take any value, but we recommend avoiding . characters. If not provided in the request, NHS Notify will default to a system generated ID in its place. The ID will be returned in a response header.\n","required":false,"deprecated":false,"allowEmptyValue":false,"explode":false,"allowReserved":false,"schema":{"type":"string","example":"11C46F5F-CDEF-4865-94B2-0EE0EDCC26DA"}}},"content":{"application/vnd.api+json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"type":{"enum":["Letter"],"type":"string"},"id":{"type":"string","example":"2WL5eYSWGzCHlGmzNxuqVusPxDg"},"attributes":{"required":["specificationId","status"],"type":"object","properties":{"specificationId":{"type":"string","example":"2WL5eYSWGzCHlGmzNxuqVusPxDg"},"groupId":{"type":"string","example":"abc123"},"status":{"enum":["PENDING","ACCEPTED","REJECTED","PRINTED","ENCLOSED","CANCELLED","DISPATCHED","DELIVERED","FAILED","RETURNED","FORWARDED"],"type":"string","description":"The supplier status of an individual letter","default":"PENDING","example":"PENDING"},"reasonCode":{"type":"string","description":"Reason code for the given status","example":"R01"},"reasonText":{"type":"string","description":"Reason text for the given status","example":"failed validation"}}}}}}}},"examples":{"get-letters":{"value":{"data":[{"attributes":{"groupId":"c5d93f917f5546d08beccf770a915d96","specificationId":"2WL5eYSWGzCHlGmzNxuqVusPxDg","status":"PENDING"},"id":"fcfd849ceec940e8832b41f4fc161e09","type":"Letter"},{"attributes":{"groupId":"c5d93f917f5546d08beccf770a915d96","specificationId":"2WL5eYSWGzCHlGmzNxuqVusPxDg","status":"PENDING"},"id":"7d64bd6a49e14213b47abbf6357eba0c","type":"Letter"},{"attributes":{"groupId":"c5d93f917f5546d08beccf770a915d96","specificationId":"2WL5eYSWGzCHlGmzNxuqVusPxDg","status":"PENDING"},"id":"2c06e7e32db4445fbbf56e7af223e0a2","type":"Letter"},{"attributes":{"groupId":"c5d93f917f5546d08beccf770a915d96","specificationId":"2WL5eYSWGzCHlGmzNxuqVusPxDg","status":"PENDING"},"id":"3b302a6122854695b5c514a4d28d18d5","type":"Letter"},{"attributes":{"groupId":"c5d93f917f5546d08beccf770a915d96","specificationId":"2WL5eYSWGzCHlGmzNxuqVusPxDg","status":"PENDING"},"id":"fbe3a53aac764a17a834699b8779958c","type":"Letter"},{"attributes":{"groupId":"c5d93f917f5546d08beccf770a915d96","specificationId":"2WL5eYSWGzCHlGmzNxuqVusPxDg","status":"PENDING"},"id":"393056c7cdc649deb29ee8d2651f29dd","type":"Letter"},{"attributes":{"groupId":"c5d93f917f5546d08beccf770a915d96","specificationId":"2WL5eYSWGzCHlGmzNxuqVusPxDg","status":"PENDING"},"id":"c6d0d4243f004b4e844003fbf80a9105","type":"Letter"},{"attributes":{"groupId":"c5d93f917f5546d08beccf770a915d96","specificationId":"853817f0-d797-4eb2-bf40-2879a9b58117","status":"PENDING"},"id":"03aa3fb76d544ad483984bdd7fcd900b","type":"Letter"},{"attributes":{"groupId":"c5d93f917f5546d08beccf770a915d96","specificationId":"9e5d5da7-5991-4ac9-9cee-559769912ca5","status":"PENDING"},"id":"7c9b698bf434479cabd0af946cc93f95","type":"Letter"},{"attributes":{"groupId":"c5d93f917f5546d08beccf770a915d96","specificationId":"634bcc87-fcc3-41fe-b6f9-c6a2125758e6","status":"PENDING"},"id":"987276fd0dc94ddbab607d4a24693db2","type":"Letter"},{"attributes":{"groupId":"c5d93f917f5546d08beccf770a915d96","specificationId":"634bcc87-fcc3-41fe-b6f9-c6a2125758e6","status":"PENDING"},"id":"32mAKk67isO29atr37M40VV8h4t","type":"Letter"},{"attributes":{"groupId":"c5d93f917f5546d08beccf770a915d96","specificationId":"634bcc87-fcc3-41fe-b6f9-c6a2125758e6","status":"PENDING"},"id":"32mAKiDtfmA1SCybeljxWaXsTO4","type":"Letter"},{"attributes":{"groupId":"c5d93f917f5546d08beccf770a915d96","specificationId":"634bcc87-fcc3-41fe-b6f9-c6a2125758e6","status":"PENDING"},"id":"32mAKeUmf6fBK2aCc5tK2AV8NLo","type":"Letter"},{"attributes":{"groupId":"c5d93f917f5546d08beccf770a915d96","specificationId":"634bcc87-fcc3-41fe-b6f9-c6a2125758e6","status":"PENDING"},"id":"32mAKg0opQaKuPrBaA11MGPTX1p","type":"Letter"},{"attributes":{"groupId":"c5d93f917f5546d08beccf770a915d96","specificationId":"634bcc87-fcc3-41fe-b6f9-c6a2125758e6","status":"PENDING"},"id":"32mAKjTJgMPTE4HdpgTvJcUmmW7","type":"Letter"},{"attributes":{"groupId":"c5d93f917f5546d08beccf770a915d96","specificationId":"634bcc87-fcc3-41fe-b6f9-c6a2125758e6","status":"PENDING"},"id":"32mAKfx3DNyUmzXMZ4zby3vh5gi","type":"Letter"},{"attributes":{"groupId":"c5d93f917f5546d08beccf770a915d96","specificationId":"634bcc87-fcc3-41fe-b6f9-c6a2125758e6","status":"PENDING"},"id":"32mAKlVCTgh4h1sTw6aiVcFdIwv","type":"Letter"},{"attributes":{"groupId":"c5d93f917f5546d08beccf770a915d96","specificationId":"634bcc87-fcc3-41fe-b6f9-c6a2125758e6","status":"PENDING"},"id":"32mAKirJUuWKB3aoGr6KkFObelC","type":"Letter"},{"attributes":{"groupId":"c5d93f917f5546d08beccf770a915d96","specificationId":"634bcc87-fcc3-41fe-b6f9-c6a2125758e6","status":"PENDING"},"id":"32mAKiUtgkjc3rS0xIYsqDOYYT4","type":"Letter"},{"attributes":{"groupId":"c5d93f917f5546d08beccf770a915d96","specificationId":"634bcc87-fcc3-41fe-b6f9-c6a2125758e6","status":"PENDING"},"id":"32mAKiQJZr3k2TBYboLgUWlR5NO","type":"Letter"},{"attributes":{"groupId":"c5d93f917f5546d08beccf770a915d96","specificationId":"634bcc87-fcc3-41fe-b6f9-c6a2125758e6","status":"PENDING"},"id":"32mAfv3V8RlfqSXOOtIZzNdjBFK","type":"Letter"},{"attributes":{"groupId":"c5d93f917f5546d08beccf770a915d96","specificationId":"634bcc87-fcc3-41fe-b6f9-c6a2125758e6","status":"PENDING"},"id":"32mAft7hTg2lKQhXhAxbPQTBudU","type":"Letter"},{"attributes":{"groupId":"c5d93f917f5546d08beccf770a915d96","specificationId":"634bcc87-fcc3-41fe-b6f9-c6a2125758e6","status":"PENDING"},"id":"32mAfv2nn1a9Kbfh4z19OyZw8Fo","type":"Letter"}]}}}}}},"400":{"description":"Bad request, invalid input data","content":{"application/vnd.api+json":{"schema":{"type":"object","properties":{"errors":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"code":{"enum":["NOTIFY_INTERNAL_SERVER_ERROR","NOTIFY_INVALID_REQUEST","NOTIFY_LETTER_NOT_FOUND"],"type":"string"},"links":{"type":"object","properties":{"about":{"type":"string","format":"uri"}}},"status":{"type":"string"},"title":{"type":"string"},"detail":{"type":"string"}}}}}},"examples":{"error-bad-request-unknown-parameter":{"value":{"errors":[{"code":"NOTIFY_INVALID_REQUEST","detail":"Only 'limit' query parameter is supported","id":"rrt-1931948104716186917-c-geu2-10664-3111479-3.0","links":{"about":"https://digital.nhs.uk/developer/api-catalogue/nhs-notify-supplier"},"status":"400","title":"Invalid request"}]}},"error-bad-request-invalid-limit":{"value":{"errors":[{"code":"NOTIFY_INVALID_REQUEST","detail":"The limit parameter must be a positive number not greater than 2500","id":"rrt-1931948104716186917-c-geu2-10664-3111479-3.0","links":{"about":"https://digital.nhs.uk/developer/api-catalogue/nhs-notify-supplier"},"status":"400","title":"Invalid request"}]}}}}}},"429":{"description":"Too many requests","content":{"application/vnd.api+json":{"schema":{"type":"object","properties":{"errors":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"code":{"enum":["NOTIFY_INTERNAL_SERVER_ERROR","NOTIFY_INVALID_REQUEST","NOTIFY_LETTER_NOT_FOUND"],"type":"string"},"links":{"type":"object","properties":{"about":{"type":"string","format":"uri"}}},"status":{"type":"string"},"title":{"type":"string"},"detail":{"type":"string"}}}}}},"examples":{"error-too-many-requests":{"value":{"errors":[{"code":"NOTIFY_QUOTA","detail":"You have made too many requests. Please try again later.","id":"rrt-1931948104716186917-c-geu2-10664-3111479-3.0","links":{"about":"https://digital.nhs.uk/developer/api-catalogue/nhs-notify-supplier"},"status":"429","title":"Too many requests"}]}}}}}},"500":{"description":"Server error","content":{"application/vnd.api+json":{"schema":{"type":"object","properties":{"errors":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"code":{"enum":["NOTIFY_INTERNAL_SERVER_ERROR","NOTIFY_INVALID_REQUEST","NOTIFY_LETTER_NOT_FOUND"],"type":"string"},"links":{"type":"object","properties":{"about":{"type":"string","format":"uri"}}},"status":{"type":"string"},"title":{"type":"string"},"detail":{"type":"string"}}}}}},"examples":{"error-server-error":{"value":{"errors":[{"code":"NOTIFY_INTERNAL_SERVER_ERROR","detail":"An unexpected error occurred, please contact support","id":"rrt-1931948104716186917-c-geu2-10664-3111479-3.0","links":{"about":"https://digital.nhs.uk/developer/api-catalogue/nhs-notify-supplier"},"status":"500","title":"Internal Server Error"}]}}}}}}},"deprecated":false},"post":{"tags":["letter"],"summary":"Update the status of multiple letters","description":"## Overview\n\nUse 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.\n\nUse this endpoint when you need to report status changes for several letters at once.\n\nWhen you make a POST update request with the endpoint, it will respond with a successful (202) response code or an unsuccessful (4xx/5xx) response.\n\nRate limiting applies. On excess requests, you may receive **429 Too Many Requests** (example error code(s): `NOTIFY_QUOTA`). Back off and retry later.\n\n### Statuses\n\nAllowed `status` values that can be used to are:\n\n- `ACCEPTED`\n- `CANCELLED`\n- `DELIVERED`\n- `DISPATCHED`\n- `ENCLOSED`\n- `FAILED`\n- `FORWARDED`\n- `PRINTED`\n- `REJECTED`\n- `RETURNED`\n\nIt is not possible to update a letter to status of `PENDING`.\n\nOptionally a `reasonCode` and `reasonText` explaining the status (for example, validation failures) can be included in the request body for each update.\n","operationId":"postLetters","requestBody":{"content":{"application/vnd.api+json":{"schema":{"required":["data"],"type":"object","properties":{"data":{"type":"array","items":{"required":["type","id","attributes"],"type":"object","properties":{"type":{"enum":["Letter"],"type":"string"},"id":{"type":"string","example":"2WL5eYSWGzCHlGmzNxuqVusPxDg"},"attributes":{"required":["status"],"type":"object","properties":{"status":{"enum":["PENDING","ACCEPTED","REJECTED","PRINTED","ENCLOSED","CANCELLED","DISPATCHED","DELIVERED","FAILED","RETURNED","FORWARDED"],"type":"string","description":"The supplier status of an individual letter","default":"PENDING","example":"PENDING"},"reasonCode":{"type":"string","description":"Reason code for the given status","example":"R01"},"reasonText":{"type":"string","description":"Reason text for the given status","example":"failed validation"}}}}}}}},"examples":{"post-letter-request":{"value":{"data":[{"attributes":{"status":"PENDING"},"id":"2WL5eYSWGzCHlGmzNxuqVusPxDg","type":"Letter"},{"attributes":{"status":"ACCEPTED"},"id":"2WL5eYSWGzCHlGmzNxuqVusPxDg","type":"Letter"},{"attributes":{"status":"PRINTED"},"id":"2WL5eYSWGzCHlGmzNxuqVusPxDg","type":"Letter"},{"attributes":{"status":"ENCLOSED"},"id":"2WL5eYSWGzCHlGmzNxuqVusPxDg","type":"Letter"},{"attributes":{"status":"DISPATCHED"},"id":"2WL5eYSWGzCHlGmzNxuqVusPxDg","type":"Letter"},{"attributes":{"status":"DELIVERED"},"id":"2WL5eYSWGzCHlGmzNxuqVusPxDg","type":"Letter"},{"attributes":{"reasonCode":"R01","reasonText":"failed validation","status":"RETURNED"},"id":"2WL5eYSWGzCHlGmzNxuqVusPxDg","type":"Letter"},{"attributes":{"reasonCode":"R01","reasonText":"failed validation","status":"CANCELLED"},"id":"2WL5eYSWGzCHlGmzNxuqVusPxDg","type":"Letter"},{"attributes":{"reasonCode":"R01","reasonText":"failed validation","status":"FAILED"},"id":"2WL5eYSWGzCHlGmzNxuqVusPxDg","type":"Letter"},{"attributes":{"reasonCode":"R01","reasonText":"failed validation","status":"RETURNED"},"id":"2WL5eYSWGzCHlGmzNxuqVusPxDg","type":"Letter"}]}}}}},"required":false},"responses":{"202":{"description":"202 (Accepted) Acknowledges that status updates have been posted","headers":{"X-Request-ID":{"name":"","in":"header","description":"Unique request identifier, in the format of a GUID\n","required":false,"deprecated":false,"allowEmptyValue":false,"explode":false,"allowReserved":false,"schema":{"type":"string","example":"dcb9c8dc-c2f4-4d5f-8674-a2e913e040b2"}},"X-Correlation-ID":{"name":"","in":"header","description":"An optional ID which you can use to track transactions across multiple systems. It can take any value, but we recommend avoiding . characters. If not provided in the request, NHS Notify will default to a system generated ID in its place. The ID will be returned in a response header.\n","required":false,"deprecated":false,"allowEmptyValue":false,"explode":false,"allowReserved":false,"schema":{"type":"string","example":"11C46F5F-CDEF-4865-94B2-0EE0EDCC26DA"}}}},"400":{"description":"Bad request, invalid input data","content":{"application/vnd.api+json":{"schema":{"type":"object","properties":{"errors":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"code":{"enum":["NOTIFY_INTERNAL_SERVER_ERROR","NOTIFY_INVALID_REQUEST","NOTIFY_LETTER_NOT_FOUND"],"type":"string"},"links":{"type":"object","properties":{"about":{"type":"string","format":"uri"}}},"status":{"type":"string"},"title":{"type":"string"},"detail":{"type":"string"}}}}}},"examples":{"error-bad-request":{"value":{"errors":[{"code":"NOTIFY_INVALID_REQUEST","detail":"Invalid request, please refer to the API specifications","id":"rrt-1931948104716186917-c-geu2-10664-3111479-3.0","links":{"about":"https://digital.nhs.uk/developer/api-catalogue/nhs-notify-supplier"},"status":"400","title":"Invalid request"}]}}}}}},"429":{"description":"Too many requests","content":{"application/vnd.api+json":{"schema":{"type":"object","properties":{"errors":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"code":{"enum":["NOTIFY_INTERNAL_SERVER_ERROR","NOTIFY_INVALID_REQUEST","NOTIFY_LETTER_NOT_FOUND"],"type":"string"},"links":{"type":"object","properties":{"about":{"type":"string","format":"uri"}}},"status":{"type":"string"},"title":{"type":"string"},"detail":{"type":"string"}}}}}},"examples":{"error-too-many-requests":{"value":{"errors":[{"code":"NOTIFY_QUOTA","detail":"You have made too many requests. Please try again later.","id":"rrt-1931948104716186917-c-geu2-10664-3111479-3.0","links":{"about":"https://digital.nhs.uk/developer/api-catalogue/nhs-notify-supplier"},"status":"429","title":"Too many requests"}]}}}}}},"500":{"description":"Server error","content":{"application/vnd.api+json":{"schema":{"type":"object","properties":{"errors":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"code":{"enum":["NOTIFY_INTERNAL_SERVER_ERROR","NOTIFY_INVALID_REQUEST","NOTIFY_LETTER_NOT_FOUND"],"type":"string"},"links":{"type":"object","properties":{"about":{"type":"string","format":"uri"}}},"status":{"type":"string"},"title":{"type":"string"},"detail":{"type":"string"}}}}}},"examples":{"error-server-error":{"value":{"errors":[{"code":"NOTIFY_INTERNAL_SERVER_ERROR","detail":"An unexpected error occurred, please contact support","id":"rrt-1931948104716186917-c-geu2-10664-3111479-3.0","links":{"about":"https://digital.nhs.uk/developer/api-catalogue/nhs-notify-supplier"},"status":"500","title":"Internal Server Error"}]}}}}}}},"deprecated":false},"parameters":[{"name":"X-Request-ID","in":"header","description":"Unique request identifier, in the format of a GUID","required":true,"deprecated":false,"allowEmptyValue":false,"explode":false,"allowReserved":false,"schema":{"type":"string","example":"dcb9c8dc-c2f4-4d5f-8674-a2e913e040b2"}},{"name":"X-Correlation-ID","in":"header","description":"An optional ID which you can use to track transactions across multiple systems. It can take any value, but we recommend avoiding `.` characters. If not provided in the request, NHS Notify will default to a system generated ID in its place.\nThe ID will be returned in a response header.","required":false,"deprecated":false,"allowEmptyValue":false,"explode":false,"allowReserved":false,"schema":{"type":"string","example":"11C46F5F-CDEF-4865-94B2-0EE0EDCC26DA"}}]},"/letters/{id}":{"get":{"tags":["letter"],"summary":"Retrieve the status of a letter","description":"## Overview\n\nUse this endpoint to get the current status of a single letter by its ID.\n\nRate limiting applies. On excess requests, you may receive **429 Too Many Requests** (example error code(s): `NOTIFY_QUOTA`). Back off and retry later.\n\n## Sandbox test scenarios\n\nYou can test the following scenarios in our sandbox environment\n\n| Scenario                                | Letter Id                    |\n| ----------------------------------------| ---------------------------- |\n| Retrieve a PENDING letter status        | `24L5eYSWGzCHlGmzNxuqVusPxDg`|\n| Retrieve a ACCEPTED letter status       | `2AL5eYSWGzCHlGmzNxuqVusPxDg`|\n| Retrieve a PRINTED letter status        | `2BL5eYSWGzCHlGmzNxuqVusPxDg`|\n| Retrieve a ENCLOSED letter status       | `2CL5eYSWGzCHlGmzNxuqVusPxDg`|\n| Retrieve a DISPATCHED letter status     | `2DL5eYSWGzCHlGmzNxuqVusPxDg`|\n| Retrieve a DELIVERED letter status      | `2EL5eYSWGzCHlGmzNxuqVusPxDg`|\n| Retrieve a REJECTED letter status       | `2WL5eYSWGzCHlGmzNxuqVusPxDg`|\n| Retrieve a CANCELLED letter status      | `2XL5eYSWGzCHlGmzNxuqVusPxDg`|\n| Retrieve a FAILED letter status         | `2YL5eYSWGzCHlGmzNxuqVusPxDg`|\n| Retrieve a RETURNED letter status       | `2ZL5eYSWGzCHlGmzNxuqVusPxDg`|\n","operationId":"getLetterStatus","responses":{"200":{"description":"Letter status","headers":{"X-Request-ID":{"name":"","in":"header","description":"Unique request identifier, in the format of a GUID\n","required":false,"deprecated":false,"allowEmptyValue":false,"explode":false,"allowReserved":false,"schema":{"type":"string","example":"dcb9c8dc-c2f4-4d5f-8674-a2e913e040b2"}},"X-Correlation-ID":{"name":"","in":"header","description":"An optional ID which you can use to track transactions across multiple systems. It can take any value, but we recommend avoiding . characters. If not provided in the request, NHS Notify will default to a system generated ID in its place. The ID will be returned in a response header.\n","required":false,"deprecated":false,"allowEmptyValue":false,"explode":false,"allowReserved":false,"schema":{"type":"string","example":"11C46F5F-CDEF-4865-94B2-0EE0EDCC26DA"}}},"content":{"application/vnd.api+json":{"schema":{"required":["data"],"type":"object","properties":{"data":{"type":"object","properties":{"type":{"enum":["Letter"],"type":"string"},"id":{"type":"string","example":"2WL5eYSWGzCHlGmzNxuqVusPxDg"},"attributes":{"required":["specificationId","status"],"type":"object","properties":{"specificationId":{"type":"string","example":"2WL5eYSWGzCHlGmzNxuqVusPxDg"},"groupId":{"type":"string","example":"abc123"},"status":{"enum":["PENDING","ACCEPTED","REJECTED","PRINTED","ENCLOSED","CANCELLED","DISPATCHED","DELIVERED","FAILED","RETURNED","FORWARDED"],"type":"string","description":"The supplier status of an individual letter","default":"PENDING","example":"PENDING"},"reasonCode":{"type":"string","description":"Reason code for the given status","example":"R01"},"reasonText":{"type":"string","description":"Reason text for the given status","example":"failed validation"}}}}}}},"examples":{"get-letters":{"value":{"data":{"attributes":{"groupId":"c5d93f917f5546d08beccf770a915d96","specificationId":"2WL5eYSWGzCHlGmzNxuqVusPxDg","status":"PENDING"},"id":"24L5eYSWGzCHlGmzNxuqVusPxDg","type":"Letter"}}}}}}},"404":{"description":"Resource not found","content":{"application/vnd.api+json":{"schema":{"type":"object","properties":{"errors":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"code":{"enum":["NOTIFY_INTERNAL_SERVER_ERROR","NOTIFY_INVALID_REQUEST","NOTIFY_LETTER_NOT_FOUND"],"type":"string"},"links":{"type":"object","properties":{"about":{"type":"string","format":"uri"}}},"status":{"type":"string"},"title":{"type":"string"},"detail":{"type":"string"}}}}}},"examples":{"error-not-found":{"value":{"errors":[{"code":"NOTIFY_RESOURCE_NOT_FOUND","detail":"No resource found with that ID","id":"rrt-1931948104716186917-c-geu2-10664-3111479-3.0","links":{"about":"https://digital.nhs.uk/developer/api-catalogue/nhs-notify-supplier"},"status":"404","title":"Resource not found"}]}}}}}},"429":{"description":"Too many requests","content":{"application/vnd.api+json":{"schema":{"type":"object","properties":{"errors":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"code":{"enum":["NOTIFY_INTERNAL_SERVER_ERROR","NOTIFY_INVALID_REQUEST","NOTIFY_LETTER_NOT_FOUND"],"type":"string"},"links":{"type":"object","properties":{"about":{"type":"string","format":"uri"}}},"status":{"type":"string"},"title":{"type":"string"},"detail":{"type":"string"}}}}}},"examples":{"error-too-many-requests":{"value":{"errors":[{"code":"NOTIFY_QUOTA","detail":"You have made too many requests. Please try again later.","id":"rrt-1931948104716186917-c-geu2-10664-3111479-3.0","links":{"about":"https://digital.nhs.uk/developer/api-catalogue/nhs-notify-supplier"},"status":"429","title":"Too many requests"}]}}}}}},"500":{"description":"Server error","content":{"application/vnd.api+json":{"schema":{"type":"object","properties":{"errors":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"code":{"enum":["NOTIFY_INTERNAL_SERVER_ERROR","NOTIFY_INVALID_REQUEST","NOTIFY_LETTER_NOT_FOUND"],"type":"string"},"links":{"type":"object","properties":{"about":{"type":"string","format":"uri"}}},"status":{"type":"string"},"title":{"type":"string"},"detail":{"type":"string"}}}}}},"examples":{"error-server-error":{"value":{"errors":[{"code":"NOTIFY_INTERNAL_SERVER_ERROR","detail":"An unexpected error occurred, please contact support","id":"rrt-1931948104716186917-c-geu2-10664-3111479-3.0","links":{"about":"https://digital.nhs.uk/developer/api-catalogue/nhs-notify-supplier"},"status":"500","title":"Internal Server Error"}]}}}}}}},"deprecated":false},"patch":{"tags":["letter"],"summary":"Update the status of a letter","description":"## Overview\n\nUse 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.\n\nWhen you make a PATCH request with your application, the endpoint will respond with an accepted (202) response code or an unsuccessful (4xx/5xx) response.\n\nRate limiting applies. On excess requests, you may receive **429 Too Many Requests** (example error code(s): `NOTIFY_QUOTA`). Back off and retry later.\n\n### Statuses\n\nAllowed `status` values that can be used to are:\n\n- `ACCEPTED`\n- `CANCELLED`\n- `DELIVERED`\n- `DISPATCHED`\n- `ENCLOSED`\n- `FAILED`\n- `FORWARDED`\n- `PRINTED`\n- `REJECTED`\n- `RETURNED`\n\nIt is not possible to update a letter to status of `PENDING`.\n\nOptionally a `reasonCode` and `reasonText` explaining the status (for example, validation failures) can be included in the request body.\n","operationId":"patchLetter","requestBody":{"content":{"application/vnd.api+json":{"schema":{"required":["data"],"type":"object","properties":{"data":{"required":["type","id","attributes"],"type":"object","properties":{"type":{"enum":["Letter"],"type":"string"},"id":{"type":"string","example":"2WL5eYSWGzCHlGmzNxuqVusPxDg"},"attributes":{"required":["status"],"type":"object","properties":{"status":{"enum":["PENDING","ACCEPTED","REJECTED","PRINTED","ENCLOSED","CANCELLED","DISPATCHED","DELIVERED","FAILED","RETURNED","FORWARDED"],"type":"string","description":"The supplier status of an individual letter","default":"PENDING","example":"PENDING"},"reasonCode":{"type":"string","description":"Reason code for the given status","example":"R01"},"reasonText":{"type":"string","description":"Reason text for the given status","example":"failed validation"}}}}}}},"examples":{"patch-letter-request-default":{"summary":"Request for default (PENDING) update","value":{"data":{"id":"2WL5eYSWGzCHlGmzNxuqVusPxDg","type":"Letter"}}},"patch-letter-request-pending":{"summary":"Request for PENDING update","value":{"data":{"attributes":{"status":"PENDING"},"id":"2WL5eYSWGzCHlGmzNxuqVusPxDg","type":"Letter"}}},"patch-letter-request-accepted":{"summary":"Request for ACCEPTED update","value":{"data":{"attributes":{"status":"ACCEPTED"},"id":"2WL5eYSWGzCHlGmzNxuqVusPxDg","type":"Letter"}}},"patch-letter-request-rejected":{"summary":"Request for REJECTED update","value":{"data":{"attributes":{"reasonCode":"R01","reasonText":"failed validation","status":"REJECTED"},"id":"2WL5eYSWGzCHlGmzNxuqVusPxDg","type":"Letter"}}},"patch-letter-request-printed":{"summary":"Request for PRINTED update","value":{"data":{"attributes":{"status":"PRINTED"},"id":"2WL5eYSWGzCHlGmzNxuqVusPxDg","type":"Letter"}}},"patch-letter-request-enclosed":{"summary":"Request for ENCLOSED update","value":{"data":{"attributes":{"status":"ENCLOSED"},"id":"2WL5eYSWGzCHlGmzNxuqVusPxDg","type":"Letter"}}},"patch-letter-request-cancelled":{"summary":"Request for CANCELLED update","value":{"data":{"attributes":{"reasonCode":"R01","reasonText":"failed validation","status":"CANCELLED"},"id":"2WL5eYSWGzCHlGmzNxuqVusPxDg","type":"Letter"}}},"patch-letter-request-dispatched":{"summary":"Request for DISPATCHED update","value":{"data":{"attributes":{"status":"DISPATCHED"},"id":"2WL5eYSWGzCHlGmzNxuqVusPxDg","type":"Letter"}}},"patch-letter-request-delivered":{"summary":"Request for DELIVERED update","value":{"data":{"attributes":{"status":"DELIVERED"},"id":"2WL5eYSWGzCHlGmzNxuqVusPxDg","type":"Letter"}}},"patch-letter-request-failed":{"summary":"Request for FAILED update","value":{"data":{"attributes":{"reasonCode":"R01","reasonText":"failed validation","status":"FAILED"},"id":"2WL5eYSWGzCHlGmzNxuqVusPxDg","type":"Letter"}}},"patch-letter-request-returned":{"summary":"Request for RETURNED update","value":{"data":{"attributes":{"reasonCode":"R01","reasonText":"failed validation","status":"REJECTED"},"id":"2WL5eYSWGzCHlGmzNxuqVusPxDg","type":"Letter"}}},"patch-letter-request-invalid":{"summary":"Request for an invalid update","value":{"data":{"attributes":{"status":"INVALID_STATUS"},"id":"2WL5eYSWGzCHlGmzNxuqVusPxDg","type":"Letter"}}},"patch-letter-request-not-found":{"summary":"Request for a non existant letter","value":{"data":{"attributes":{"status":"ACCEPTED"},"id":"123654789","type":"Letter"}}}}}},"required":false},"responses":{"202":{"description":"202 (Accepted) Acknowledges Letter resource update has been received","headers":{"X-Request-ID":{"name":"","in":"header","description":"Unique request identifier, in the format of a GUID\n","required":false,"deprecated":false,"allowEmptyValue":false,"explode":false,"allowReserved":false,"schema":{"type":"string","example":"dcb9c8dc-c2f4-4d5f-8674-a2e913e040b2"}},"X-Correlation-ID":{"name":"","in":"header","description":"An optional ID which you can use to track transactions across multiple systems. It can take any value, but we recommend avoiding . characters. If not provided in the request, NHS Notify will default to a system generated ID in its place. The ID will be returned in a response header.\n","required":false,"deprecated":false,"allowEmptyValue":false,"explode":false,"allowReserved":false,"schema":{"type":"string","example":"11C46F5F-CDEF-4865-94B2-0EE0EDCC26DA"}}}},"400":{"description":"Bad request, invalid input data","content":{"application/vnd.api+json":{"schema":{"type":"object","properties":{"errors":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"code":{"enum":["NOTIFY_INTERNAL_SERVER_ERROR","NOTIFY_INVALID_REQUEST","NOTIFY_LETTER_NOT_FOUND"],"type":"string"},"links":{"type":"object","properties":{"about":{"type":"string","format":"uri"}}},"status":{"type":"string"},"title":{"type":"string"},"detail":{"type":"string"}}}}}},"examples":{"error-bad-request-invalid-request-body":{"value":{"errors":[{"code":"NOTIFY_INVALID_REQUEST","detail":"The request body is invalid","id":"rrt-1931948104716186917-c-geu2-10664-3111479-3.0","links":{"about":"https://digital.nhs.uk/developer/api-catalogue/nhs-notify-supplier"},"status":"400","title":"Invalid request"}]}}}}}},"404":{"description":"Resource not found","content":{"application/vnd.api+json":{"schema":{"type":"object","properties":{"errors":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"code":{"enum":["NOTIFY_INTERNAL_SERVER_ERROR","NOTIFY_INVALID_REQUEST","NOTIFY_LETTER_NOT_FOUND"],"type":"string"},"links":{"type":"object","properties":{"about":{"type":"string","format":"uri"}}},"status":{"type":"string"},"title":{"type":"string"},"detail":{"type":"string"}}}}}},"examples":{"error-not-found":{"value":{"errors":[{"code":"NOTIFY_RESOURCE_NOT_FOUND","detail":"No resource found with that ID","id":"rrt-1931948104716186917-c-geu2-10664-3111479-3.0","links":{"about":"https://digital.nhs.uk/developer/api-catalogue/nhs-notify-supplier"},"status":"404","title":"Resource not found"}]}}}}}},"429":{"description":"Too many requests","content":{"application/vnd.api+json":{"schema":{"type":"object","properties":{"errors":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"code":{"enum":["NOTIFY_INTERNAL_SERVER_ERROR","NOTIFY_INVALID_REQUEST","NOTIFY_LETTER_NOT_FOUND"],"type":"string"},"links":{"type":"object","properties":{"about":{"type":"string","format":"uri"}}},"status":{"type":"string"},"title":{"type":"string"},"detail":{"type":"string"}}}}}},"examples":{"error-too-many-requests":{"value":{"errors":[{"code":"NOTIFY_QUOTA","detail":"You have made too many requests. Please try again later.","id":"rrt-1931948104716186917-c-geu2-10664-3111479-3.0","links":{"about":"https://digital.nhs.uk/developer/api-catalogue/nhs-notify-supplier"},"status":"429","title":"Too many requests"}]}}}}}},"500":{"description":"Server error","content":{"application/vnd.api+json":{"schema":{"type":"object","properties":{"errors":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"code":{"enum":["NOTIFY_INTERNAL_SERVER_ERROR","NOTIFY_INVALID_REQUEST","NOTIFY_LETTER_NOT_FOUND"],"type":"string"},"links":{"type":"object","properties":{"about":{"type":"string","format":"uri"}}},"status":{"type":"string"},"title":{"type":"string"},"detail":{"type":"string"}}}}}},"examples":{"error-server-error":{"value":{"errors":[{"code":"NOTIFY_INTERNAL_SERVER_ERROR","detail":"An unexpected error occurred, please contact support","id":"rrt-1931948104716186917-c-geu2-10664-3111479-3.0","links":{"about":"https://digital.nhs.uk/developer/api-catalogue/nhs-notify-supplier"},"status":"500","title":"Internal Server Error"}]}}}}}}},"deprecated":false},"parameters":[{"name":"X-Request-ID","in":"header","description":"Unique request identifier, in the format of a GUID","required":true,"deprecated":false,"allowEmptyValue":false,"explode":false,"allowReserved":false,"schema":{"type":"string","example":"dcb9c8dc-c2f4-4d5f-8674-a2e913e040b2"}},{"name":"X-Correlation-ID","in":"header","description":"An optional ID which you can use to track transactions across multiple systems. It can take any value, but we recommend avoiding `.` characters. If not provided in the request, NHS Notify will default to a system generated ID in its place.\nThe ID will be returned in a response header.","required":false,"deprecated":false,"allowEmptyValue":false,"explode":false,"allowReserved":false,"schema":{"type":"string","example":"11C46F5F-CDEF-4865-94B2-0EE0EDCC26DA"}},{"name":"id","in":"path","description":"Unique identifier of this resource","required":true,"deprecated":false,"allowEmptyValue":false,"explode":false,"allowReserved":false,"schema":{"type":"string","example":"24L5eYSWGzCHlGmzNxuqVusPxDg"}}]},"/letters/{id}/data":{"get":{"tags":["data"],"summary":"Fetch a data file","description":"## Overview\n\nUse this endpoint to get letter data, including downloading the letter's print-ready PDF file.\n\nRate limiting applies. On excess requests, you may receive **429 Too Many Requests** (example error code(s): `NOTIFY_QUOTA`). Back off and retry later.\n\n## Sandbox test scenarios\n\nYou can test the following scenarios in our sandbox environment.\n\n|Scenario|Request ID|Response|\n|--------|-------|--------|\n|Success  | 2AL5eYSWGzCHlGmzNxuqVusPxDg | Returns 303 (See Other) and URL to an example PDF in the Location header |\n|Not found |2WL5eYSWGzCHlGmzNxuqVusPxDg | Returns 404 Not found and error details in the response |\n","operationId":"getDataId","responses":{"303":{"description":"See Other","headers":{"Location":{"name":"","in":"header","description":"The signed S3 URL of the data file to download","required":false,"deprecated":false,"allowEmptyValue":false,"explode":false,"allowReserved":false,"schema":{"type":"string"},"example":"https://examples3bucket.com/filelocation"},"X-Request-ID":{"name":"","in":"header","description":"Unique request identifier, in the format of a GUID\n","required":false,"deprecated":false,"allowEmptyValue":false,"explode":false,"allowReserved":false,"schema":{"type":"string","example":"dcb9c8dc-c2f4-4d5f-8674-a2e913e040b2"}},"X-Correlation-ID":{"name":"","in":"header","description":"An optional ID which you can use to track transactions across multiple systems. It can take any value, but we recommend avoiding . characters. If not provided in the request, NHS Notify will default to a system generated ID in its place. The ID will be returned in a response header.\n","required":false,"deprecated":false,"allowEmptyValue":false,"explode":false,"allowReserved":false,"schema":{"type":"string","example":"11C46F5F-CDEF-4865-94B2-0EE0EDCC26DA"}}}},"404":{"description":"Resource not found","content":{"application/vnd.api+json":{"schema":{"type":"object","properties":{"errors":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"code":{"enum":["NOTIFY_INTERNAL_SERVER_ERROR","NOTIFY_INVALID_REQUEST","NOTIFY_LETTER_NOT_FOUND"],"type":"string"},"links":{"type":"object","properties":{"about":{"type":"string","format":"uri"}}},"status":{"type":"string"},"title":{"type":"string"},"detail":{"type":"string"}}}}}},"examples":{"error-not-found":{"value":{"errors":[{"code":"NOTIFY_RESOURCE_NOT_FOUND","detail":"No resource found with that ID","id":"rrt-1931948104716186917-c-geu2-10664-3111479-3.0","links":{"about":"https://digital.nhs.uk/developer/api-catalogue/nhs-notify-supplier"},"status":"404","title":"Resource not found"}]}}}}}},"429":{"description":"Too many requests","content":{"application/vnd.api+json":{"schema":{"type":"object","properties":{"errors":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"code":{"enum":["NOTIFY_INTERNAL_SERVER_ERROR","NOTIFY_INVALID_REQUEST","NOTIFY_LETTER_NOT_FOUND"],"type":"string"},"links":{"type":"object","properties":{"about":{"type":"string","format":"uri"}}},"status":{"type":"string"},"title":{"type":"string"},"detail":{"type":"string"}}}}}},"examples":{"error-too-many-requests":{"value":{"errors":[{"code":"NOTIFY_QUOTA","detail":"You have made too many requests. Please try again later.","id":"rrt-1931948104716186917-c-geu2-10664-3111479-3.0","links":{"about":"https://digital.nhs.uk/developer/api-catalogue/nhs-notify-supplier"},"status":"429","title":"Too many requests"}]}}}}}},"500":{"description":"Server error","content":{"application/vnd.api+json":{"schema":{"type":"object","properties":{"errors":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"code":{"enum":["NOTIFY_INTERNAL_SERVER_ERROR","NOTIFY_INVALID_REQUEST","NOTIFY_LETTER_NOT_FOUND"],"type":"string"},"links":{"type":"object","properties":{"about":{"type":"string","format":"uri"}}},"status":{"type":"string"},"title":{"type":"string"},"detail":{"type":"string"}}}}}},"examples":{"error-server-error":{"value":{"errors":[{"code":"NOTIFY_INTERNAL_SERVER_ERROR","detail":"An unexpected error occurred, please contact support","id":"rrt-1931948104716186917-c-geu2-10664-3111479-3.0","links":{"about":"https://digital.nhs.uk/developer/api-catalogue/nhs-notify-supplier"},"status":"500","title":"Internal Server Error"}]}}}}}}},"deprecated":false},"parameters":[{"name":"id","in":"path","description":"Unique identifier of this resource","required":true,"deprecated":false,"allowEmptyValue":false,"explode":false,"allowReserved":false,"schema":{"type":"string","example":"24L5eYSWGzCHlGmzNxuqVusPxDg"}},{"name":"X-Request-ID","in":"header","description":"Unique request identifier, in the format of a GUID","required":true,"deprecated":false,"allowEmptyValue":false,"explode":false,"allowReserved":false,"schema":{"type":"string","example":"dcb9c8dc-c2f4-4d5f-8674-a2e913e040b2"}},{"name":"X-Correlation-ID","in":"header","description":"An optional ID which you can use to track transactions across multiple systems. It can take any value, but we recommend avoiding `.` characters. If not provided in the request, NHS Notify will default to a system generated ID in its place.\nThe ID will be returned in a response header.","required":false,"deprecated":false,"allowEmptyValue":false,"explode":false,"allowReserved":false,"schema":{"type":"string","example":"11C46F5F-CDEF-4865-94B2-0EE0EDCC26DA"}}]},"/mi":{"post":{"tags":["mi"],"summary":"Create a new MI record","description":"## Overview\n\nUse this endpoint to send management or operational metrics relating to letter processing and print fulfilment.\n\nWhen you submit a create management information request, the endpoint will respond with a 201 (Created) response code along with the created data including a unique id for the record or an unsuccessful (4xx/5xx) response.\n\nRate limiting applies. On excess requests, you may receive **429 Too Many Requests** (example error code(s): `NOTIFY_QUOTA`). Back off and retry later.\n\n## Sandbox test scenarios\n\nYou can test the following scenarios in our sandbox environment.\n\n|Scenario|Request|Response|\n|--------|-------|--------|\n|Success|Request for successful MI record Creation| 201 (Created) with the created management information in the response|\n|Invalid Request|Invalid Request for MI record Creation| 400 (Bad Request) with the error details in the body|\n|Unknown specification|Request for MI record Creation for unknown spec|404 (Not Found)  with the error details in the body|\n","operationId":"createMI","requestBody":{"content":{"application/vnd.api+json":{"schema":{"type":"object","properties":{"data":{"required":["type","attributes"],"type":"object","properties":{"type":{"enum":["ManagementInformation"],"type":"string"},"attributes":{"required":["lineItem","timestamp","quantity"],"type":"object","properties":{"lineItem":{"type":"string","description":"A line item reference that should match an invoice line item","example":"envelope-business-standard"},"timestamp":{"type":"string","description":"The effective date of the activity being reported","format":"date-time","example":"2023-11-17T14:27:51.413Z"},"quantity":{"type":"number","description":"The quantity of the line item being reported","example":22},"specificationId":{"type":"string","description":"A specification ID provided in the Letter request that this MI relates to","example":"da0b1495-c7cb-468c-9d81-07dee089d728"},"groupId":{"type":"string","description":"A group ID provided in the Letter request that this MI relates to","example":"abc123"},"stockRemaining":{"type":"number","description":"Stock remaining for this line item, where applicable","example":20000}}}}}}},"examples":{"create-mi-request-success":{"summary":"Request for successful MI record Creation","value":{"data":{"attributes":{"groupId":"abc123","lineItem":"envelope-business-standard","quantity":22,"specificationId":"2WL5eYSWGzCHlGmzNxuqVusPxDg","stockRemaining":2000,"timestamp":"2023-11-17T14:27:51.413Z"},"type":"ManagementInformation"}}},"create-mi-request-invalid":{"summary":"Invalid Request for MI record Creation","value":{"data":{"attributes":{"groupId":"abc123","lineItem":"envelope-business-standard","quantity":22,"specificationId":"2WL5eYSWGzCHlGmzNxuqVusPxDg","stockRemaining":2000,"timestamp":"yesterday"},"type":"ManagementInformation"}}},"create-mi-request-notfound":{"summary":"Request for MI record Creation for unknown spec","value":{"data":{"attributes":{"groupId":"abc123","lineItem":"envelope-business-standard","quantity":22,"specificationId":"123456","stockRemaining":2000,"timestamp":"2023-11-17T14:27:51.413Z"},"type":"ManagementInformation"}}}}}},"required":false},"responses":{"201":{"description":"Management Information created successfully","headers":{"X-Request-ID":{"name":"","in":"header","description":"Unique request identifier, in the format of a GUID\n","required":false,"deprecated":false,"allowEmptyValue":false,"explode":false,"allowReserved":false,"schema":{"type":"string","example":"dcb9c8dc-c2f4-4d5f-8674-a2e913e040b2"}},"X-Correlation-ID":{"name":"","in":"header","description":"An optional ID which you can use to track transactions across multiple systems. It can take any value, but we recommend avoiding . characters. If not provided in the request, NHS Notify will default to a system generated ID in its place. The ID will be returned in a response header.\n","required":false,"deprecated":false,"allowEmptyValue":false,"explode":false,"allowReserved":false,"schema":{"type":"string","example":"11C46F5F-CDEF-4865-94B2-0EE0EDCC26DA"}}},"content":{"application/vnd.api+json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"type":{"enum":["ManagementInformation"],"type":"string"},"id":{"type":"string","example":"2WL5eYSWGzCHlGmzNxuqVusPxDg"},"attributes":{"required":["lineItem","timestamp","quantity"],"type":"object","properties":{"lineItem":{"type":"string","description":"A line item reference that should match an invoice line item","example":"envelope-business-standard"},"timestamp":{"type":"string","description":"The effective date of the activity being reported","format":"date-time","example":"2023-11-17T14:27:51.413Z"},"quantity":{"type":"number","description":"The quantity of the line item being reported","example":22},"specificationId":{"type":"string","description":"A specification ID provided in the Letter request that this MI relates to","example":"da0b1495-c7cb-468c-9d81-07dee089d728"},"groupId":{"type":"string","description":"A group ID provided in the Letter request that this MI relates to","example":"abc123"},"stockRemaining":{"type":"number","description":"Stock remaining for this line item, where applicable","example":20000}}}}}}},"examples":{"create-mi-response":{"value":{"data":{"attributes":{"groupId":"abc123","lineItem":"envelope-business-standard","quantity":22,"specificationId":"2WL5eYSWGzCHlGmzNxuqVusPxDg","stockRemaining":2000,"timestamp":"2023-11-17T14:27:51.413Z"},"id":"2WL5eYSWGzCHlGmzNxuqVusPxDg","type":"ManagementInformation"}}}}}}},"400":{"description":"Bad request, invalid input data","content":{"application/vnd.api+json":{"schema":{"type":"object","properties":{"errors":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"code":{"enum":["NOTIFY_INTERNAL_SERVER_ERROR","NOTIFY_INVALID_REQUEST","NOTIFY_LETTER_NOT_FOUND"],"type":"string"},"links":{"type":"object","properties":{"about":{"type":"string","format":"uri"}}},"status":{"type":"string"},"title":{"type":"string"},"detail":{"type":"string"}}}}}},"examples":{"error-bad-request":{"value":{"errors":[{"code":"NOTIFY_INVALID_REQUEST","detail":"Invalid request, please refer to the API specifications","id":"rrt-1931948104716186917-c-geu2-10664-3111479-3.0","links":{"about":"https://digital.nhs.uk/developer/api-catalogue/nhs-notify-supplier"},"status":"400","title":"Invalid request"}]}}}}}},"429":{"description":"Too many requests","content":{"application/vnd.api+json":{"schema":{"type":"object","properties":{"errors":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"code":{"enum":["NOTIFY_INTERNAL_SERVER_ERROR","NOTIFY_INVALID_REQUEST","NOTIFY_LETTER_NOT_FOUND"],"type":"string"},"links":{"type":"object","properties":{"about":{"type":"string","format":"uri"}}},"status":{"type":"string"},"title":{"type":"string"},"detail":{"type":"string"}}}}}},"examples":{"error-too-many-requests":{"value":{"errors":[{"code":"NOTIFY_QUOTA","detail":"You have made too many requests. Please try again later.","id":"rrt-1931948104716186917-c-geu2-10664-3111479-3.0","links":{"about":"https://digital.nhs.uk/developer/api-catalogue/nhs-notify-supplier"},"status":"429","title":"Too many requests"}]}}}}}},"500":{"description":"Server error","content":{"application/vnd.api+json":{"schema":{"type":"object","properties":{"errors":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"code":{"enum":["NOTIFY_INTERNAL_SERVER_ERROR","NOTIFY_INVALID_REQUEST","NOTIFY_LETTER_NOT_FOUND"],"type":"string"},"links":{"type":"object","properties":{"about":{"type":"string","format":"uri"}}},"status":{"type":"string"},"title":{"type":"string"},"detail":{"type":"string"}}}}}},"examples":{"error-server-error":{"value":{"errors":[{"code":"NOTIFY_INTERNAL_SERVER_ERROR","detail":"An unexpected error occurred, please contact support","id":"rrt-1931948104716186917-c-geu2-10664-3111479-3.0","links":{"about":"https://digital.nhs.uk/developer/api-catalogue/nhs-notify-supplier"},"status":"500","title":"Internal Server Error"}]}}}}}}},"deprecated":false},"parameters":[{"name":"X-Request-ID","in":"header","description":"Unique request identifier, in the format of a GUID","required":true,"deprecated":false,"allowEmptyValue":false,"explode":false,"allowReserved":false,"schema":{"type":"string","example":"dcb9c8dc-c2f4-4d5f-8674-a2e913e040b2"}},{"name":"X-Correlation-ID","in":"header","description":"An optional ID which you can use to track transactions across multiple systems. It can take any value, but we recommend avoiding `.` characters. If not provided in the request, NHS Notify will default to a system generated ID in its place.\nThe ID will be returned in a response header.","required":false,"deprecated":false,"allowEmptyValue":false,"explode":false,"allowReserved":false,"schema":{"type":"string","example":"11C46F5F-CDEF-4865-94B2-0EE0EDCC26DA"}}]},"/_status":{"get":{"summary":"Health check","description":"Returns 200 OK if the service is up.","operationId":"getStatus","responses":{"200":{"description":"Service is healthy"}},"deprecated":false}}},"components":{"securitySchemes":{"app-level3":{"$ref":"https://proxygen.ptl.api.platform.nhs.uk/components/securitySchemes/app-level3"},"app-level0":{"$ref":"https://proxygen.ptl.api.platform.nhs.uk/components/securitySchemes/app-level0"}}},"security":[{"app-level0":[]}],"tags":[{"name":"letter","description":""},{"name":"mi","description":""},{"name":"data","description":""}]}