{"openapi":"3.0.0","info":{"version":"v4.65.0","title":"NHS Notify API","description":"## Overview\n\nUse this API to send messages to citizens via NHS App, email, text message or letter.\n\n[NHS Notify](https://digital.nhs.uk/services/nhs-notify) provides:\n\n* message templating\n* message routing\n* enrichment of recipient details\n* support for accessible formats and multiple languages\n\nLearn more about [NHS Notify's features](https://notify.nhs.uk/features/).\n\n## Who can use this API\n\nThe NHS Notify service is intended for services involved in direct care. This API can only be used where you have a legal basis to issue communications to citizens.\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\nYou can comment, upvote and view progress on [our roadmap](https://nhs-digital-api-management.featureupvote.com/?order=top&filter=allexceptdone&tag=nhs-notify-api).\n\nIf you have any other queries, [contact us](https://digital.nhs.uk/developer/help-and-support).\n\n## Service level\n\nThis service is a [gold](https://digital.nhs.uk/services/reference-guide#service-levels) service, meaning it is available and supported 24 hours a day, 365 days a year.\n\nFor more details, including incident resolution times, see [service levels](https://digital.nhs.uk/developer/guides-and-documentation/reference-guide#service-levels).\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 formats:\n\n* `application/vnd.api+json` - see [JSON:API specification](https://jsonapi.org/format/#introduction)\n* `application/json`\n\nBoth of these formats have the same structure - the API responds with a standard JSON document.\n\nYou can use the `Accept` header to control which `Content-Type` is returned in the response.\n\nThe `Accept` header can contain the following values:\n\n* `*/*`\n* `application/json`\n* `application/vnd.api+json`\n\nThe `Accept` 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 `415` error response. If omitted then `utf-8` is assumed. \n\nWhere no `Accept` header is present, this will default to `application/vnd.api+json`\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## Security and authorisation\n\nThis 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.\n\nAuthentication and authorisation of end users is the responsibility of your application.\n\nTo access this API, use the following 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## Environments and testing\n\n| Environment | Base URL |\n|------------ | -------- |\n| Sandbox | `https://sandbox.api.service.nhs.uk/comms` |\n| Integration test | `https://int.api.service.nhs.uk/comms` |\n| Production | `https://api.service.nhs.uk/comms` |\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 our 'Try this API' feature, see the documentation for each endpoint.\n\nAlternatively, you can try out the sandbox using our Postman collection:\n\n[](https://www.postman.com/nhs-communications-manager/communications-manager/collection/41628342-33dcc9d0-8ccc-4756-8ccb-237fd78337f5/?action=share&creator=41628342)\n\nYou can find our postman collection source in our [public repository on github](https://github.com/NHSDigital/communications-manager-api/tree/master/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 can try out our integration environment using our Postman collection. This Postman collection contains the signed JWT authentication mechanism, allowing you to test our integration environment without writing any code:\n\n[](https://www.postman.com/nhs-communications-manager/communications-manager/collection/cna2c8u/nhs-notify-integration?action=share&creator=41628342)\n\nAlternatively you can find our postman collection source in our [public repository on github](https://github.com/NHSDigital/communications-manager-api/tree/master/postman).\n\n### Production smoke testing\n\nYou must not send communications to real patients for smoke testing in the production environment.\n\nSmoke testing is permitted only using the NHS Notify production test patients. When you onboard to NHS Notify, our onboarding team will get in touch to put together a smoke test plan. Smoke testing will be done one day prior to go live.\n\n## Onboarding\n\nYou need to get your software approved by us before it can go live with this API.\n\nYou will also need to follow our steps to [onboard with NHS Notify](https://notify.nhs.uk/get-started/onboard-with-nhs-notify).\n\n## Enable users to write and send messages from your software\n\nNHS Notify can deliver NHS App messages, emails and text messages that your users write in your software's free-text inputs.\n\nThis is also useful if you:\n\n* do not need to set up reusable templates for multiple recipients\n* want to send individual messages\n\n### Setting up your free-text inputs\nYou'll need to configure your free-text inputs to populate one of our personalisation fields. Each personalisation field is specific to a message channel and will contain the entire message content that your user will enter in your software.\n\nYou'll then need to include this personalisation field in your request.\n\n###\tMaking your request to send messages from your software\nUse the following routing plan IDs and personalisation fields that match the message channel your user will send their message with.\n\n| Message channel | First message channel delivery failure time | Second message channel delivery failure time | Personalisation fields | Routing plan ID | \n|-------------------------------------------------------|---------------------------------------------|----------------------------------------------|----------------------------------------|--------------------------------------|\n| NHS App message | 24 hours | - | body | 00000000-0000-0000-0000-000000000001 |\n| Email | 72 hours | - | email_subject, email_body | 00000000-0000-0000-0000-000000000002 |\n| Text message | 72 hours | - | sms_body | 00000000-0000-0000-0000-000000000003 |\n| NHS App message with a fallback to Email | 24 hours | 72 hours | nhsapp_body, email_subject, email_body | 00000000-0000-0000-0000-000000000004 |\n| NHS App message with a fallback to Email | 4 hours | 72 hours | nhsapp_body, email_subject, email_body | 00000000-0000-0000-0000-000000000005 |\n| NHS App message with a fallback to Text message | 24 hours | 72 hours | nhsapp_body, sms_body | 00000000-0000-0000-0000-000000000006 |\n| NHS App message with a fallback to Text message | 4 hours | 72 hours | nhsapp_body, sms_body | 00000000-0000-0000-0000-000000000007 |\n\nFor email, use the personalisation field `email_subject` to allow your user to add the email subject line.\n\nComplete your request in the same way you [send a single message](#post-/v1/messages) or [send a batch of messages](#post-/v1/message-batches).\n\nYou can try out example requests in the sandbox environment in our [Postman collection](#overview--environments-and-testing).\n\n### Delivery failure or fallback time\nThis is the maximum amount of time we'll attempt to deliver the message for each message channel in the routing plan before the message gets a 'failed' status.\n\nWe'll then attempt to deliver the message using the second available message channel, if the routing plan includes one.\n\nFind out more about [message, channel and supplier statuses](https://notify.nhs.uk/using-nhs-notify/message-channel-supplier-status).\n\n### Formatting messages written in your software\nYou can use Markdown to add formatting that your users apply to NHS App messages and emails they write in your software.\n\nFor NHS App messages, follow the Markdown guidance in the 'contentString' section of the schema (opens in a new tab).\n\nFor emails, follow the Markdown guidance for:\n* links and URLs (opens in a new tab)\n* bullet points, headings, horizontal lines, inset text and numbered steps (opens in a new tab)\n\nYour users will not be able to use personalisation offered by NHS Notify (opens in a new tab) in messages they write from your software.\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 for more on errors](https://digital.nhs.uk/developer/guides-and-documentation/reference-guide#http-status-codes).\n\n## Receive a callback\n\nYou may develop one or many endpoints on your service if you want to receive callbacks from NHS Notify.\n\nWe have created an OpenAPI specification detailing the behaviour of the endpoint that consumers should create to subscribe to callbacks.\n\nWe will send your API key in the `x-api-key header`. Your service should respond with:\n\n* `401 Unauthorized` if the API key is not received\n* `401 Unauthorized` if the API key is invalid\n\nWe will send you a HMAC-SHA256 signature in the `x-hmac-sha256-signature` header. You will need to validate the signature to verify the response has come from NHS Notify.\nThis can be achieved by hashing the request body using the HMAC-SHA256 algorithm with a secret value that is comprised of a concatenation of your APIM application ID and the API key that we provide you. The secret takes the following form `[APPLICATION_ID].[API_KEY]`. If you receive a request with an invalid signature you should ignore it and respond with a `403 Forbidden`.\n\nEvery request includes an `idempotencyKey` field located in the meta collection of the body. This can help ensure your system remains idempotent, capable of managing duplicate delivery of callbacks. It's important to note that requests may be delivered non-sequentially.\n\nIf a request fails, our retry policy will continue to attempt to deliver the callback for a period of 2 hours.\n\n## Message character limits\nDifferent character limits apply to each of the communication channels as listed below. NHS Notify will validate that any personalisation fields submitted in the send message request do not exceed these limits but it is the client's responsibility to ensure that when personalisation is combined with any templated text, the channel character limit is not exceeded.\n\n| Channel | Character Limit |\n|--------------------|-----------------|\n| Email | 100,000 |\n| Letter | 15,000 |\n| NHS App | 5,000 |\n| Text message (SMS) | 918 |","contact":{"name":"NHS Notify API Support","url":"https://digital.nhs.uk/developer/help-and-support","email":"api.management@nhs.net"}},"servers":[{"url":"https://sandbox.api.service.nhs.uk/comms","description":"Sandbox environment"},{"url":"https://int.api.service.nhs.uk/comms","description":"Integration test environment"},{"url":"https://api.service.nhs.uk/comms","description":"Production environment"}],"paths":{"/v1/message-batches":{"post":{"summary":"Send a batch of messages","description":"## Overview\n\nUse this endpoint to send a batch of messages to 1 or more NHS patients.\n\n### References\n\nYou must provide two reference values within the payload to this endpoint:\n\n- A message batch reference\n- A per message reference\n\nThe message batch reference (`messageBatchReference`) is unique for you. This value is used to store your reference for this batch of messages.\n\nThe per message reference (`messageReference`) needs to be unique within the message batch. This value is used to store your reference for this specific message within the batch.\n\n### Personalisation\n\nYou may be required to send through specific personalisation fields based upon the routing plan (`routingPlanId`). These will have been setup during your [onboarding](#overview--onboarding) process.\n\nMessages that are missing required personalisation fields, or have personalisation content that is too long for the routing plan that it is used in, will be accepted by the API but will not be sent.\n\n### Sandbox\n\nWhen sending this request on sandbox you must use one of the 6 preconfigured routing plan identifiers:\n\n- `b838b13c-f98c-4def-93f0-515d4e4f4ee1`\n- `49e43b98-70cb-47a9-a55e-fe70c9a6f77c`\n- `b402cd20-b62a-4357-8e02-2952959531c8`\n- `936e9d45-15de-4a95-bb36-ae163c33ae53`\n- `9ba00d23-cd6f-4aca-8688-00abc85a7980`\n- `00000000-0000-0000-0000-000000000001`\n\nOn other environments these values will be established as part of your [NHS Notify onboarding](#overview--onboarding).\n\nHere is an example curl request which creates a message batch using one of these routing plan identifiers:\n\n```\n curl -X POST \\\n --header \"Accept: */*\" \\\n --header \"Content-type: application/vnd.api+json\" \\\n -d '{\"data\": {\"type\": \"MessageBatch\",\"attributes\": {\"routingPlanId\": \"b838b13c-f98c-4def-93f0-515d4e4f4ee1\",\"messageBatchReference\": \"da0b1495-c7cb-468c-9d81-07dee089d728\",\"messages\": [{\"messageReference\": \"703b8008-545d-4a04-bb90-1f2946ce1575\",\"recipient\": {\"nhsNumber\": \"9990548609\"},\"originator\": {\"odsCode\":\"X123\"},\"personalisation\": {}}]}}}' \\\n https://sandbox.api.service.nhs.uk/comms/v1/message-batches\n```\n","operationId":"create-message-batch","parameters":[{"name":"Authorization","in":"header","description":"An [OAuth 2.0 bearer token](https://digital.nhs.uk/developer/guides-and-documentation/security-and-authorisation/application-restricted-restful-apis-signed-jwt-authentication).\nRequired in all environments except sandbox.","schema":{"type":"string","format":"^Bearer [[:ascii:]]+$","example":"Bearer g1112R_ccQ1Ebbb4gtHBP1aaaNM"}},{"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.","schema":{"type":"string","example":"11C46F5F-CDEF-4865-94B2-0EE0EDCC26DA"}}],"requestBody":{"description":"","content":{"application/vnd.api+json":{"schema":{"type":"object","title":"Create message batch","properties":{"data":{"type":"object","properties":{"type":{"title":"Enum_MessageBatch","type":"string","enum":["MessageBatch"],"example":"MessageBatch"},"attributes":{"description":"MessageBatch attributes.","type":"object","properties":{"routingPlanId":{"type":"string","description":"This is the routing plan you wish your batch to use whilst sending messages to the recipients. The values available to you for this are setup during your [onboarding process](#overview--onboarding).\n\nThere are also some global routingPlanIds available, please see the [Free-text communications documentation](#section/Free-text-communications).\n\nIf you send through an invalid routing plan id you will receive a 404 response.","format":"uuid","example":"b838b13c-f98c-4def-93f0-515d4e4f4ee1"},"messageBatchReference":{"type":"string","description":"This is a client-supplied unique reference for this batch of messages.\n\nThis value is used internally to de-duplicate batches. If you send the same value through multiple times only one of the requests will be actioned.","example":"da0b1495-c7cb-468c-9d81-07dee089d728"},"messages":{"type":"array","items":{"type":"object","title":"Message","additionalProperties":false,"properties":{"messageReference":{"type":"string","description":"This reference needs to be unique per message within this batch. If there are duplicate values then a 400 exception will be thrown highlighting the values that have been duplicated.","example":"703b8008-545d-4a04-bb90-1f2946ce1575"},"billingReference":{"type":"string","description":"Optional reference for billing purposes. Can be any string.","example":"billing-ref-1"},"recipient":{"type":"object","title":"Recipient","additionalProperties":false,"properties":{"nhsNumber":{"type":"string","pattern":"^\\d{10}$","minLength":10,"maxLength":10,"example":"9990548609","description":"The [NHS number](https://digital.nhs.uk/services/nhs-number) of the recipient. Only [valid NHS Numbers](https://www.datadictionary.nhs.uk/attributes/nhs_number.html) will be accepted. This will be used to lookup the recipients details with the [Personal Demographics Service](https://digital.nhs.uk/developer/api-catalogue/personal-demographics-service-fhir). Normally a required field, unless prior agreement with the Onboarding team is in place."},"contactDetails":{"type":"object","description":"Overriding contact details is a sensitive action and requires explicit approval from the onboarding team.","properties":{"email":{"type":"string","pattern":"[A-Za-z0-9._%+-]+@[A-Za-z0-9.-]+\\.[A-Z|a-z]{2,}","minLength":6,"maxLength":90,"description":"Overriding email address for recipient.","example":"recipient@nhs.net"},"sms":{"type":"string","description":"Overriding mobile number for the recipient. Must be in a valid UK format or international format with a country code.\n\nLearn more about [sending text messages to international numbers](https://notify.nhs.uk/pricing/text-messages#sending-text-messages-to-international-numbers).\n","example":"07777777777"},"address":{"type":"object","description":"Overriding address.","properties":{"lines":{"type":"array","minItems":2,"maxItems":5,"description":"Lines of overriding address.","items":{"type":"string"},"example":["NHS England","6th Floor","7&8 Wellington Place","Leeds","West Yorkshire"]},"postcode":{"type":"string","description":"Postcode of overriding address. A required field when address is specified. Must be a valid UK postcode format.","example":"LS1 4AP"}}},"name":{"type":"object","description":"Overriding name fields for the recipient.","properties":{"prefix":{"type":"string","description":"Prefix of overriding name.","example":"Dr."},"firstName":{"type":"string","description":"First name of overriding name.","example":"John"},"middleNames":{"type":"string","description":"Middle names of overriding name.","example":"Andrew Robert"},"lastName":{"type":"string","description":"Last name of overriding name. A required field when name is specified.","example":"Smith"},"suffix":{"type":"string","description":"Suffix of overriding name.","example":"Jr."}}}}}}},"originator":{"type":"object","title":"Originator","additionalProperties":false,"properties":{"odsCode":{"type":"string","description":"ODS code used to identify the sender when using the NHS App channel (allowOdsOverride must be enabled on the corresponding NHS Notify client).","example":"X26"}}},"personalisation":{"type":"object","description":"The personalisation keys and values for this message. These are linked to the routingPlanId provided and are agreed upon during [onboarding](#overview--onboarding)."}},"required":["messageReference","recipient"]}}},"required":["routingPlanId","messageBatchReference","messages"]}},"required":["type","attributes"]}},"required":["data"]}},"application/json":{"schema":{"type":"object","title":"Create message batch","properties":{"data":{"type":"object","properties":{"type":{"title":"Enum_MessageBatch","type":"string","enum":["MessageBatch"],"example":"MessageBatch"},"attributes":{"description":"MessageBatch attributes.","type":"object","properties":{"routingPlanId":{"type":"string","description":"This is the routing plan you wish your batch to use whilst sending messages to the recipients. The values available to you for this are setup during your [onboarding process](#overview--onboarding).\n\nThere are also some global routingPlanIds available, please see the [Free-text communications documentation](#section/Free-text-communications).\n\nIf you send through an invalid routing plan id you will receive a 404 response.","format":"uuid","example":"b838b13c-f98c-4def-93f0-515d4e4f4ee1"},"messageBatchReference":{"type":"string","description":"This is a client-supplied unique reference for this batch of messages.\n\nThis value is used internally to de-duplicate batches. If you send the same value through multiple times only one of the requests will be actioned.","example":"da0b1495-c7cb-468c-9d81-07dee089d728"},"messages":{"type":"array","items":{"type":"object","title":"Message","additionalProperties":false,"properties":{"messageReference":{"type":"string","description":"This reference needs to be unique per message within this batch. If there are duplicate values then a 400 exception will be thrown highlighting the values that have been duplicated.","example":"703b8008-545d-4a04-bb90-1f2946ce1575"},"billingReference":{"type":"string","description":"Optional reference for billing purposes. Can be any string.","example":"billing-ref-1"},"recipient":{"type":"object","title":"Recipient","additionalProperties":false,"properties":{"nhsNumber":{"type":"string","pattern":"^\\d{10}$","minLength":10,"maxLength":10,"example":"9990548609","description":"The [NHS number](https://digital.nhs.uk/services/nhs-number) of the recipient. Only [valid NHS Numbers](https://www.datadictionary.nhs.uk/attributes/nhs_number.html) will be accepted. This will be used to lookup the recipients details with the [Personal Demographics Service](https://digital.nhs.uk/developer/api-catalogue/personal-demographics-service-fhir). Normally a required field, unless prior agreement with the Onboarding team is in place."},"contactDetails":{"type":"object","description":"Overriding contact details is a sensitive action and requires explicit approval from the onboarding team.","properties":{"email":{"type":"string","pattern":"[A-Za-z0-9._%+-]+@[A-Za-z0-9.-]+\\.[A-Z|a-z]{2,}","minLength":6,"maxLength":90,"description":"Overriding email address for recipient.","example":"recipient@nhs.net"},"sms":{"type":"string","description":"Overriding mobile number for the recipient. Must be in a valid UK format or international format with a country code.\n\nLearn more about [sending text messages to international numbers](https://notify.nhs.uk/pricing/text-messages#sending-text-messages-to-international-numbers).\n","example":"07777777777"},"address":{"type":"object","description":"Overriding address.","properties":{"lines":{"type":"array","minItems":2,"maxItems":5,"description":"Lines of overriding address.","items":{"type":"string"},"example":["NHS England","6th Floor","7&8 Wellington Place","Leeds","West Yorkshire"]},"postcode":{"type":"string","description":"Postcode of overriding address. A required field when address is specified. Must be a valid UK postcode format.","example":"LS1 4AP"}}},"name":{"type":"object","description":"Overriding name fields for the recipient.","properties":{"prefix":{"type":"string","description":"Prefix of overriding name.","example":"Dr."},"firstName":{"type":"string","description":"First name of overriding name.","example":"John"},"middleNames":{"type":"string","description":"Middle names of overriding name.","example":"Andrew Robert"},"lastName":{"type":"string","description":"Last name of overriding name. A required field when name is specified.","example":"Smith"},"suffix":{"type":"string","description":"Suffix of overriding name.","example":"Jr."}}}}}}},"originator":{"type":"object","title":"Originator","additionalProperties":false,"properties":{"odsCode":{"type":"string","description":"ODS code used to identify the sender when using the NHS App channel (allowOdsOverride must be enabled on the corresponding NHS Notify client).","example":"X26"}}},"personalisation":{"type":"object","description":"The personalisation keys and values for this message. These are linked to the routingPlanId provided and are agreed upon during [onboarding](#overview--onboarding)."}},"required":["messageReference","recipient"]}}},"required":["routingPlanId","messageBatchReference","messages"]}},"required":["type","attributes"]}},"required":["data"]}}}},"responses":{"201":{"description":"Your message batch has been created. The backend service will process the messages contained within it according to the routing plan identified in the request.\n\nThe response includes an array with your `messageReference` and our message `id` for each message in your request.\nYou should store these IDs so that you can later query the message status using the [Get the status of a message](#get-/v1/messages/-messageId-) endpoint.\n","content":{"application/vnd.api+json":{"schema":{"type":"object","title":"Message batch response","additionalProperties":false,"properties":{"data":{"type":"object","additionalProperties":false,"required":["type","id","attributes"],"properties":{"type":{"title":"Enum_MessageBatch","type":"string","enum":["MessageBatch"],"example":"MessageBatch"},"id":{"description":"Identifier for this MessageBatch. You should store this identifier for later lookups.","example":"2ZljUiS8NjJNs95PqiYOO7gAfJb","type":"string","title":"Type_KSUID","pattern":"^[a-zA-Z0-9]{27}$","minLength":27,"maxLength":27},"attributes":{"type":"object","additionalProperties":false,"required":["messageBatchReference","routingPlan","messages"],"properties":{"messageBatchReference":{"type":"string","description":"Your unique message batch reference, provided within the payload to create the batch of messages.","example":"da0b1495-c7cb-468c-9d81-07dee089d728"},"routingPlan":{"description":"The routing plan that you requested the messages be sent with.","type":"object","additionalProperties":false,"required":["id","name","createdDate"],"properties":{"id":{"type":"string","format":"uuid","description":"The identifier for the routing plan.","example":"b838b13c-f98c-4def-93f0-515d4e4f4ee1"},"name":{"type":"string","description":"The name of the routing plan.","example":"Plan Abc"},"version":{"type":"string","description":"This identifies the specific version of the routing plan.","example":"ztoe2qRAM8M8vS0bqajhyEBcvXacrGPp"},"createdDate":{"type":"string","description":"The creation date of the routing plan.","format":"date-time","example":"2023-11-17T14:27:51.413Z"}}},"messages":{"type":"array","items":{"type":"object","title":"Message","additionalProperties":false,"required":["messageReference","id"],"properties":{"messageReference":{"example":"703b8008-545d-4a04-bb90-1f2946ce1575","type":"string","description":"Original reference supplied for the message."},"id":{"type":"string","title":"Type_KSUID","description":"The unique identifier for the message.","pattern":"^[a-zA-Z0-9]{27}$","minLength":27,"maxLength":27,"example":"2WL3qFTEFM0qMY8xjRbt1LIKCzM"}}}}}}}}}}},"application/json":{"schema":{"type":"object","title":"Message batch response","additionalProperties":false,"properties":{"data":{"type":"object","additionalProperties":false,"required":["type","id","attributes"],"properties":{"type":{"title":"Enum_MessageBatch","type":"string","enum":["MessageBatch"],"example":"MessageBatch"},"id":{"description":"Identifier for this MessageBatch. You should store this identifier for later lookups.","example":"2ZljUiS8NjJNs95PqiYOO7gAfJb","type":"string","title":"Type_KSUID","pattern":"^[a-zA-Z0-9]{27}$","minLength":27,"maxLength":27},"attributes":{"type":"object","additionalProperties":false,"required":["messageBatchReference","routingPlan","messages"],"properties":{"messageBatchReference":{"type":"string","description":"Your unique message batch reference, provided within the payload to create the batch of messages.","example":"da0b1495-c7cb-468c-9d81-07dee089d728"},"routingPlan":{"description":"The routing plan that you requested the messages be sent with.","type":"object","additionalProperties":false,"required":["id","name","createdDate"],"properties":{"id":{"type":"string","format":"uuid","description":"The identifier for the routing plan.","example":"b838b13c-f98c-4def-93f0-515d4e4f4ee1"},"name":{"type":"string","description":"The name of the routing plan.","example":"Plan Abc"},"version":{"type":"string","description":"This identifies the specific version of the routing plan.","example":"ztoe2qRAM8M8vS0bqajhyEBcvXacrGPp"},"createdDate":{"type":"string","description":"The creation date of the routing plan.","format":"date-time","example":"2023-11-17T14:27:51.413Z"}}},"messages":{"type":"array","items":{"type":"object","title":"Message","additionalProperties":false,"required":["messageReference","id"],"properties":{"messageReference":{"example":"703b8008-545d-4a04-bb90-1f2946ce1575","type":"string","description":"Original reference supplied for the message."},"id":{"type":"string","title":"Type_KSUID","description":"The unique identifier for the message.","pattern":"^[a-zA-Z0-9]{27}$","minLength":27,"maxLength":27,"example":"2WL3qFTEFM0qMY8xjRbt1LIKCzM"}}}}}}}}}}}},"headers":{"X-Correlation-ID":{"schema":{"type":"string","pattern":"11C46F5F-CDEF-4865-94B2-0EE0EDCC26DA","description":"If the X-Correlation-ID header was included in the request the value of this header will be equal to that. Otherwise it will be a unique alphanumeric string generated by NHS Notify."}}}},"400":{"description":"A validation error has occurred with the request body sent. Up to 100 validation errors will be returned, if there are more than 100 validation errors then the first 100 will be returned.\n\nThe following validation errors can occur:\n\n| Error code | Title | Description |\n| ---------- | ----- | ----------- |\n| `CM_MISSING_VALUE` | Missing property | The property at the specified location is required, but was not present in the request. |\n| `CM_NULL_VALUE` | Property cannot be null | The property at the specified location is required, but a null value was passed in the request. |\n| `CM_INVALID_VALUE` | Invalid value | The property at the specified location does not allow this value. |\n| `CM_INVALID_NHS_NUMBER` | Invalid nhs number | The value provided in this nhsNumber field is not a valid NHS number. |\n| `CM_DUPLICATE_VALUE` | Duplicate value | The property at the specified location is a duplicate, duplicated values are not allowed. |\n| `CM_TOO_FEW_ITEMS` | Too few items | The property at the specified location contains too few items. |\n| `CM_ODS_CODE_REQUIRED` | Originator odsCode must be provided | An originator with odsCode must be provided, as your account does not have a default ODS code. |\n| `CM_CANNOT_SET_ODS_CODE` | Cannot set ODS code | Your account is not permitted to set originator ODS codes. |\n| `CM_CANNOT_SET_CONTACT_DETAILS` | Cannot set contact details | Your account is not allowed to provide alternative contact details. |\n\nWithin each error is a source object which details the location of the error within your request body.\n\nThis is done using a pointer that uses the [JSON Pointer](https://datatracker.ietf.org/doc/html/rfc6901) as per the [JSON:API Error Specification](https://jsonapi.org/format/#errors).\n\n### Sandbox\n\nIt is possible to trigger some of the errors in the sandbox by sending the header `Authorization` with certain values.\n\nHere is an example curl request to trigger a `CM_CANNOT_SET_ODS_CODE`:\n\n```\n curl -X POST \\\n --header \"Accept: */*\" \\\n --header \"Content-type: application/vnd.api+json\" \\\n --header \"Authorization: noOdsChange\" \\\n -d '{\"data\":{\"type\":\"MessageBatch\",\"attributes\":{\"routingPlanId\":\"b838b13c-f98c-4def-93f0-515d4e4f4ee1\",\"messageBatchReference\":\"346e3fc3-0b55-4c0d-bec9-0cc5aa431836\",\"messages\":[{\"messageReference\":\"da0b1495-c7cb-468c-9d81-07dee089d728\",\"recipient\":{\"nhsNumber\":\"9990548609\"},\"originator\":{\"odsCode\":\"X123\"},\"personalisation\":{}}]}}}' \\\n https://sandbox.api.service.nhs.uk/comms/v1/message-batches\n```\n\nHere is an example curl request to trigger a `CM_CANNOT_SET_CONTACT_DETAILS`:\n\n```\n curl -X POST \\\n --header \"Accept: */*\" \\\n --header \"Content-type: application/vnd.api+json\" \\\n --header \"Authorization: notAllowedContactDetailOverride\" \\\n -d '{\"data\":{\"type\":\"MessageBatch\",\"attributes\":{\"routingPlanId\":\"b838b13c-f98c-4def-93f0-515d4e4f4ee1\",\"messageBatchReference\":\"346e3fc3-0b55-4c0d-bec9-0cc5aa431836\",\"messages\":[{\"messageReference\":\"da0b1495-c7cb-468c-9d81-07dee089d728\",\"recipient\":{\"nhsNumber\":\"9990548609\",\"contactDetails\":{\"sms\":\"07777000000\"}},\"personalisation\":{}}]}}}' \\\n https://sandbox.api.service.nhs.uk/comms/v1/message-batches\n```\n","content":{"application/vnd.api+json":{"schema":{"type":"object","title":"Request not processable","additionalProperties":false,"properties":{"errors":{"type":"array","minItems":1,"uniqueItems":true,"items":{"type":"object","additionalProperties":false,"properties":{"id":{"type":"string","title":"Type_ErrorIdentifier","description":"A system generated unique identifier for this request.","example":"rrt-1931948104716186917-c-geu2-10664-3111479-3.0"},"code":{"title":"Enum_ErrorCode","type":"string","enum":["CM_MISSING_VALUE","CM_NULL_VALUE","CM_INVALID_VALUE","CM_INVALID_NHS_NUMBER","CM_DUPLICATE_VALUE","CM_TOO_FEW_ITEMS","CM_ODS_CODE_REQUIRED","CM_CANNOT_SET_ODS_CODE"],"example":"CM_INVALID_NHS_NUMBER"},"links":{"type":"object","additionalProperties":false,"properties":{"about":{"type":"string","format":"uri","example":"https://digital.nhs.uk/developer/api-catalogue/nhs-notify","description":"https://digital.nhs.uk/developer/api-catalogue/nhs-notify"},"nhsNumbers":{"type":"string","format":"uri","example":"https://www.datadictionary.nhs.uk/attributes/nhs_number.html","description":"https://www.datadictionary.nhs.uk/attributes/nhs_number.html This link is only provided in the instance of a \"CM_INVALID_NHS_NUMBER\" error."}},"minProperties":1},"status":{"type":"string","enum":["400"],"example":"400"},"title":{"type":"string","title":"Enum_Title","description":"The title of this error response.","enum":["Missing property","Property cannot be null","Invalid value","Duplicate value","Too few items","Invalid nhs number","Originator odsCode must be provided","Cannot set ODS code"],"example":"Invalid nhs number"},"detail":{"type":"string","description":"A human-readable description of the error.","example":"The value provided in this nhsNumber field is not a valid NHS number."},"source":{"type":"object","additionalProperties":false,"properties":{"pointer":{"type":"string","description":"Indicates the path to the message and field in the request where the validation error occurred.\n\nValidation errors are referenced using a zero-based index. For example:\n- `/data/attributes/messages/0/recipient/nhsNumber` refers to the first message in the request.\n- `/data/attributes/messages/5/recipient/nhsNumber` refers to the sixth message in the request.","example":"/data/attributes/messages/0/recipient/nhsNumber"}}}}}}}}},"application/json":{"schema":{"type":"object","title":"Request not processable","additionalProperties":false,"properties":{"errors":{"type":"array","minItems":1,"uniqueItems":true,"items":{"type":"object","additionalProperties":false,"properties":{"id":{"type":"string","title":"Type_ErrorIdentifier","description":"A system generated unique identifier for this request.","example":"rrt-1931948104716186917-c-geu2-10664-3111479-3.0"},"code":{"title":"Enum_ErrorCode","type":"string","enum":["CM_MISSING_VALUE","CM_NULL_VALUE","CM_INVALID_VALUE","CM_INVALID_NHS_NUMBER","CM_DUPLICATE_VALUE","CM_TOO_FEW_ITEMS","CM_ODS_CODE_REQUIRED","CM_CANNOT_SET_ODS_CODE"],"example":"CM_INVALID_NHS_NUMBER"},"links":{"type":"object","additionalProperties":false,"properties":{"about":{"type":"string","format":"uri","example":"https://digital.nhs.uk/developer/api-catalogue/nhs-notify","description":"https://digital.nhs.uk/developer/api-catalogue/nhs-notify"},"nhsNumbers":{"type":"string","format":"uri","example":"https://www.datadictionary.nhs.uk/attributes/nhs_number.html","description":"https://www.datadictionary.nhs.uk/attributes/nhs_number.html This link is only provided in the instance of a \"CM_INVALID_NHS_NUMBER\" error."}},"minProperties":1},"status":{"type":"string","enum":["400"],"example":"400"},"title":{"type":"string","title":"Enum_Title","description":"The title of this error response.","enum":["Missing property","Property cannot be null","Invalid value","Duplicate value","Too few items","Invalid nhs number","Originator odsCode must be provided","Cannot set ODS code"],"example":"Invalid nhs number"},"detail":{"type":"string","description":"A human-readable description of the error.","example":"The value provided in this nhsNumber field is not a valid NHS number."},"source":{"type":"object","additionalProperties":false,"properties":{"pointer":{"type":"string","description":"Indicates the path to the message and field in the request where the validation error occurred.\n\nValidation errors are referenced using a zero-based index. For example:\n- `/data/attributes/messages/0/recipient/nhsNumber` refers to the first message in the request.\n- `/data/attributes/messages/5/recipient/nhsNumber` refers to the sixth message in the request.","example":"/data/attributes/messages/0/recipient/nhsNumber"}}}}}}}}}},"headers":{"X-Correlation-ID":{"schema":{"type":"string","pattern":"11C46F5F-CDEF-4865-94B2-0EE0EDCC26DA","description":"If the X-Correlation-ID header was included in the request the value of this header will be equal to that. Otherwise it will be a unique alphanumeric string generated by NHS Notify."}}}},"401":{"description":"Your request was not authorized - you need to send a `Authorization` header with a valid `Bearer` token.\n\nSee the documentation on [how to generate a valid token](https://digital.nhs.uk/developer/guides-and-documentation/security-and-authorisation/application-restricted-restful-apis-signed-jwt-authentication).\n\n### Sandbox\n\nIt is possible to trigger this error in the sandbox by sending the header `Prefer` with a value of `code=401`.\n\nHere is an example curl request to trigger a `401`:\n\n```\n curl -X GET \\\n --header \"Accept: */*\" \\\n --header \"Prefer: code=401\" \\\n https://sandbox.api.service.nhs.uk/comms/\n```\n","content":{"application/vnd.api+json":{"schema":{"type":"object","title":"Access Denied","additionalProperties":false,"properties":{"errors":{"type":"array","minItems":1,"maxItems":1,"uniqueItems":true,"items":{"type":"object","additionalProperties":false,"properties":{"id":{"type":"string","title":"Type_ErrorIdentifier","description":"A system generated unique identifier for this request.","example":"rrt-1931948104716186917-c-geu2-10664-3111479-3.0"},"code":{"title":"Enum_Error_AccessDenied","type":"string","enum":["CM_DENIED"],"example":"CM_DENIED"},"links":{"type":"object","additionalProperties":false,"properties":{"about":{"type":"string","format":"uri","example":"https://digital.nhs.uk/developer/api-catalogue/nhs-notify","description":"https://digital.nhs.uk/developer/api-catalogue/nhs-notify"}},"minProperties":1},"status":{"type":"string","enum":["401"],"example":"401"},"title":{"type":"string","enum":["Access denied"],"example":"Access denied"},"detail":{"type":"string","enum":["Access token missing, invalid or expired, or calling application not configured for this operation."],"example":"Access token missing, invalid or expired, or calling application not configured for this operation."},"source":{"type":"object","additionalProperties":false,"properties":{"header":{"type":"string","enum":["Authorization"],"example":"Authorization"}}}}}}}}},"application/json":{"schema":{"type":"object","title":"Access Denied","additionalProperties":false,"properties":{"errors":{"type":"array","minItems":1,"maxItems":1,"uniqueItems":true,"items":{"type":"object","additionalProperties":false,"properties":{"id":{"type":"string","title":"Type_ErrorIdentifier","description":"A system generated unique identifier for this request.","example":"rrt-1931948104716186917-c-geu2-10664-3111479-3.0"},"code":{"title":"Enum_Error_AccessDenied","type":"string","enum":["CM_DENIED"],"example":"CM_DENIED"},"links":{"type":"object","additionalProperties":false,"properties":{"about":{"type":"string","format":"uri","example":"https://digital.nhs.uk/developer/api-catalogue/nhs-notify","description":"https://digital.nhs.uk/developer/api-catalogue/nhs-notify"}},"minProperties":1},"status":{"type":"string","enum":["401"],"example":"401"},"title":{"type":"string","enum":["Access denied"],"example":"Access denied"},"detail":{"type":"string","enum":["Access token missing, invalid or expired, or calling application not configured for this operation."],"example":"Access token missing, invalid or expired, or calling application not configured for this operation."},"source":{"type":"object","additionalProperties":false,"properties":{"header":{"type":"string","enum":["Authorization"],"example":"Authorization"}}}}}}}}}},"headers":{"X-Correlation-ID":{"schema":{"type":"string","pattern":"11C46F5F-CDEF-4865-94B2-0EE0EDCC26DA","description":"If the X-Correlation-ID header was included in the request the value of this header will be equal to that. Otherwise it will be a unique alphanumeric string generated by NHS Notify."}}}},"403":{"description":"Your request contained an authentic bearer token in the `Authorization` header but you are not authorized to make the request.\n\nIf the error code in the response is `CM_FORBIDDEN` then this could be due to the onboarding process not having been completed. Refer to our [onboarding](#overview--onboarding) section for more information.\n\nIf the response contains the error `CM_SERVICE_BAN` then there is a ban in effect on your account.\n\n### Sandbox\n\nIt is possible to trigger the `CM_FORBIDDEN` error in the sandbox by sending the header `Prefer` with a value of `code=403`.\n\nHere is an example curl request to trigger a `CM_FORBIDDEN`:\n\n```\n curl -X GET \\\n --header \"Accept: */*\" \\\n --header \"Prefer: code=403\" \\\n https://sandbox.api.service.nhs.uk/comms/\n```\n\nTo trigger the `CM_SERVICE_BAN` error in the sandbox by sending the header `Prefer` with a value of `code=403.1`.\n\nHere is an example curl request to trigger a `CM_SERVICE_BAN`:\n\n```\n curl -X GET \\\n --header \"Accept: */*\" \\\n --header \"Prefer: code=403.1\" \\\n https://sandbox.api.service.nhs.uk/comms/\n```\n","content":{"application/vnd.api+json":{"schema":{"type":"object","title":"Forbidden","additionalProperties":false,"properties":{"errors":{"type":"array","minItems":1,"maxItems":1,"uniqueItems":true,"items":{"type":"object","additionalProperties":false,"properties":{"id":{"type":"string","title":"Type_ErrorIdentifier","description":"A system generated unique identifier for this request.","example":"rrt-1931948104716186917-c-geu2-10664-3111479-3.0"},"code":{"title":"Enum_Error_Forbidden","type":"string","enum":["CM_FORBIDDEN","CM_SERVICE_BAN"],"example":"CM_FORBIDDEN"},"links":{"type":"object","additionalProperties":false,"properties":{"about":{"type":"string","format":"uri","example":"https://digital.nhs.uk/developer/api-catalogue/nhs-notify","description":"https://digital.nhs.uk/developer/api-catalogue/nhs-notify"}},"minProperties":1},"status":{"type":"string","enum":["403"],"example":"403"},"title":{"type":"string","enum":["Forbidden","Service ban in effect"],"example":"Forbidden"},"detail":{"type":"string","enum":["Client not recognised or not yet onboarded.","A service ban is in effect on your account."],"example":"Client not recognised or not yet onboarded."},"source":{"type":"object","additionalProperties":false,"properties":{"header":{"type":"string","enum":["Authorization"],"example":"Authorization"}}}}}}}}},"application/json":{"schema":{"type":"object","title":"Forbidden","additionalProperties":false,"properties":{"errors":{"type":"array","minItems":1,"maxItems":1,"uniqueItems":true,"items":{"type":"object","additionalProperties":false,"properties":{"id":{"type":"string","title":"Type_ErrorIdentifier","description":"A system generated unique identifier for this request.","example":"rrt-1931948104716186917-c-geu2-10664-3111479-3.0"},"code":{"title":"Enum_Error_Forbidden","type":"string","enum":["CM_FORBIDDEN","CM_SERVICE_BAN"],"example":"CM_FORBIDDEN"},"links":{"type":"object","additionalProperties":false,"properties":{"about":{"type":"string","format":"uri","example":"https://digital.nhs.uk/developer/api-catalogue/nhs-notify","description":"https://digital.nhs.uk/developer/api-catalogue/nhs-notify"}},"minProperties":1},"status":{"type":"string","enum":["403"],"example":"403"},"title":{"type":"string","enum":["Forbidden","Service ban in effect"],"example":"Forbidden"},"detail":{"type":"string","enum":["Client not recognised or not yet onboarded.","A service ban is in effect on your account."],"example":"Client not recognised or not yet onboarded."},"source":{"type":"object","additionalProperties":false,"properties":{"header":{"type":"string","enum":["Authorization"],"example":"Authorization"}}}}}}}}}},"headers":{"X-Correlation-ID":{"schema":{"type":"string","pattern":"11C46F5F-CDEF-4865-94B2-0EE0EDCC26DA","description":"If the X-Correlation-ID header was included in the request the value of this header will be equal to that. Otherwise it will be a unique alphanumeric string generated by NHS Notify."}}}},"404":{"description":"The routing plan identifier passed in the body has not been found.\n\nWhen you [onboarded](#overview--onboarding) onto the service a number of valid routing plan identifiers were issued to you. You must use one of these valid routing plan identifiers when requesting for a batch of messages to be sent.\n\n### Sandbox\n\nOn the sandbox environment there are 5 valid routing plan identifiers that can be used by anybody calling the API. These are:\n\n* `b838b13c-f98c-4def-93f0-515d4e4f4ee1`\n* `49e43b98-70cb-47a9-a55e-fe70c9a6f77c`\n* `b402cd20-b62a-4357-8e02-2952959531c8`\n* `936e9d45-15de-4a95-bb36-ae163c33ae53`\n* `9ba00d23-cd6f-4aca-8688-00abc85a7980`\n\nIf you use a routing plan id that is not in this list then a `404 Not Found` error response will be triggered.\n\nOn other environments these values will be established as part of your [NHS Notify onboarding](#overview--onboarding).\n\nHere is an example curl request to trigger a `404`:\n\n```\n curl -X POST \\\n --header \"Accept: */*\" \\\n --header \"Content-type: application/vnd.api+json\" \\\n -d '{\"data\": {\"type\": \"MessageBatch\",\"attributes\": {\"routingPlanId\": \"868796f9-7ce3-4730-9f1e-23aa766edea3\",\"messageBatchReference\": \"da0b1495-c7cb-468c-9d81-07dee089d728\",\"messages\": [{\"messageReference\": \"703b8008-545d-4a04-bb90-1f2946ce1575\",\"recipient\": {\"nhsNumber\": \"9990548609\"},\"originator\": {\"odsCode\":\"X123\"},\"personalisation\": {}}]}}}' \\\n https://sandbox.api.service.nhs.uk/comms/v1/message-batches\n```\n","content":{"application/vnd.api+json":{"schema":{"type":"object","title":"No such routing plan","additionalProperties":false,"properties":{"errors":{"type":"array","minItems":1,"maxItems":1,"uniqueItems":true,"items":{"type":"object","additionalProperties":false,"properties":{"id":{"type":"string","title":"Type_ErrorIdentifier","description":"A system generated unique identifier for this request.","example":"rrt-1931948104716186917-c-geu2-10664-3111479-3.0"},"code":{"title":"Enum_Error_NoSuchRoutingPlan","type":"string","enum":["CM_NO_SUCH_ROUTING_PLAN"],"example":"CM_NO_SUCH_ROUTING_PLAN"},"links":{"type":"object","additionalProperties":false,"properties":{"about":{"type":"string","format":"uri","example":"https://digital.nhs.uk/developer/api-catalogue/nhs-notify","description":"https://digital.nhs.uk/developer/api-catalogue/nhs-notify"}},"minProperties":1},"status":{"type":"string","enum":["404"],"example":"404"},"title":{"type":"string","enum":["No such routing plan"],"example":"No such routing plan"},"detail":{"type":"string","enum":["The routing plan specified either does not exist or is not in a usable state."],"example":"The routing plan specified either does not exist or is not in a usable state."},"source":{"type":"object","properties":{"pointer":{"type":"string","enum":["/data/attributes/routingPlan"],"example":"/data/attributes/routingPlan"}}}}}}}}},"application/json":{"schema":{"type":"object","title":"No such routing plan","additionalProperties":false,"properties":{"errors":{"type":"array","minItems":1,"maxItems":1,"uniqueItems":true,"items":{"type":"object","additionalProperties":false,"properties":{"id":{"type":"string","title":"Type_ErrorIdentifier","description":"A system generated unique identifier for this request.","example":"rrt-1931948104716186917-c-geu2-10664-3111479-3.0"},"code":{"title":"Enum_Error_NoSuchRoutingPlan","type":"string","enum":["CM_NO_SUCH_ROUTING_PLAN"],"example":"CM_NO_SUCH_ROUTING_PLAN"},"links":{"type":"object","additionalProperties":false,"properties":{"about":{"type":"string","format":"uri","example":"https://digital.nhs.uk/developer/api-catalogue/nhs-notify","description":"https://digital.nhs.uk/developer/api-catalogue/nhs-notify"}},"minProperties":1},"status":{"type":"string","enum":["404"],"example":"404"},"title":{"type":"string","enum":["No such routing plan"],"example":"No such routing plan"},"detail":{"type":"string","enum":["The routing plan specified either does not exist or is not in a usable state."],"example":"The routing plan specified either does not exist or is not in a usable state."},"source":{"type":"object","properties":{"pointer":{"type":"string","enum":["/data/attributes/routingPlan"],"example":"/data/attributes/routingPlan"}}}}}}}}}},"headers":{"X-Correlation-ID":{"schema":{"type":"string","pattern":"11C46F5F-CDEF-4865-94B2-0EE0EDCC26DA","description":"If the X-Correlation-ID header was included in the request the value of this header will be equal to that. Otherwise it will be a unique alphanumeric string generated by NHS Notify."}}}},"405":{"description":"Your request specified a method that was not allowed on this endpoint.\n\nEndpoints only allow certain methods to be called on them. If your method was not one of the allowed ones it will be rejected with this status code.\n\n","content":{"application/vnd.api+json":{"schema":{"type":"object","title":"Method not allowed","additionalProperties":false,"properties":{"errors":{"type":"array","minItems":1,"maxItems":1,"uniqueItems":true,"items":{"type":"object","additionalProperties":false,"properties":{"id":{"type":"string","title":"Type_ErrorIdentifier","description":"A system generated unique identifier for this request.","example":"rrt-1931948104716186917-c-geu2-10664-3111479-3.0"},"code":{"title":"Enum_Error_Method_Not_Allowed","type":"string","enum":["CM_NOT_ALLOWED"],"example":"CM_NOT_ALLOWED"},"links":{"type":"object","additionalProperties":false,"properties":{"about":{"type":"string","format":"uri","example":"https://digital.nhs.uk/developer/api-catalogue/nhs-notify","description":"https://digital.nhs.uk/developer/api-catalogue/nhs-notify"}},"minProperties":1},"status":{"type":"string","enum":["405"],"example":"405"},"title":{"type":"string","enum":["Method not allowed"],"example":"Method not allowed"},"detail":{"type":"string","enum":["The method at the requested URI was not allowed."],"example":"The method at the requested URI was not allowed."}}}}}}},"application/json":{"schema":{"type":"object","title":"Method not allowed","additionalProperties":false,"properties":{"errors":{"type":"array","minItems":1,"maxItems":1,"uniqueItems":true,"items":{"type":"object","additionalProperties":false,"properties":{"id":{"type":"string","title":"Type_ErrorIdentifier","description":"A system generated unique identifier for this request.","example":"rrt-1931948104716186917-c-geu2-10664-3111479-3.0"},"code":{"title":"Enum_Error_Method_Not_Allowed","type":"string","enum":["CM_NOT_ALLOWED"],"example":"CM_NOT_ALLOWED"},"links":{"type":"object","additionalProperties":false,"properties":{"about":{"type":"string","format":"uri","example":"https://digital.nhs.uk/developer/api-catalogue/nhs-notify","description":"https://digital.nhs.uk/developer/api-catalogue/nhs-notify"}},"minProperties":1},"status":{"type":"string","enum":["405"],"example":"405"},"title":{"type":"string","enum":["Method not allowed"],"example":"Method not allowed"},"detail":{"type":"string","enum":["The method at the requested URI was not allowed."],"example":"The method at the requested URI was not allowed."}}}}}}}},"headers":{"X-Correlation-ID":{"schema":{"type":"string","pattern":"11C46F5F-CDEF-4865-94B2-0EE0EDCC26DA","description":"If the X-Correlation-ID header was included in the request the value of this header will be equal to that. Otherwise it will be a unique alphanumeric string generated by NHS Notify."}}}},"406":{"description":"The request did not contain a valid `Accept` header value.\n\nValid values are:\n\n* `*/*`\n* `application/json`\n* `application/vnd.api+json`\n* `application/json; charset=utf-8`\n* `application/vnd.api+json; charset=utf-8`\n\nWhere no `Accept` header is present, this will default to `application/vnd.api+json`\n","content":{"application/vnd.api+json":{"schema":{"type":"object","title":"Not Acceptable","additionalProperties":false,"properties":{"errors":{"type":"array","minItems":1,"maxItems":1,"uniqueItems":true,"items":{"type":"object","additionalProperties":false,"properties":{"id":{"type":"string","title":"Type_ErrorIdentifier","description":"A system generated unique identifier for this request.","example":"rrt-1931948104716186917-c-geu2-10664-3111479-3.0"},"code":{"title":"Enum_Error_NotAcceptable","type":"string","enum":["CM_NOT_ACCEPTABLE"],"example":"CM_NOT_ACCEPTABLE"},"links":{"type":"object","additionalProperties":false,"properties":{"about":{"type":"string","format":"uri","example":"https://digital.nhs.uk/developer/api-catalogue/nhs-notify","description":"https://digital.nhs.uk/developer/api-catalogue/nhs-notify"}},"minProperties":1},"status":{"type":"string","enum":["406"],"example":"406"},"title":{"type":"string","enum":["Not acceptable"],"example":"Not acceptable"},"detail":{"type":"string","enum":["This service can only generate application/vnd.api+json or application/json."],"example":"This service can only generate application/vnd.api+json or application/json."},"source":{"type":"object","additionalProperties":false,"properties":{"header":{"type":"string","enum":["Accept"],"example":"Accept"}}}}}}}}}},"headers":{"X-Correlation-ID":{"schema":{"type":"string","pattern":"11C46F5F-CDEF-4865-94B2-0EE0EDCC26DA","description":"If the X-Correlation-ID header was included in the request the value of this header will be equal to that. Otherwise it will be a unique alphanumeric string generated by NHS Notify."}}}},"408":{"description":"There has been a client side issue reading your request. This can occur when there are networking issues between your application and our service.\n\nThere may also be an issue within our backend where a `408` has been bubbled up and exposed.\n\nThis could be indicative of an ongoing infrastructure issue that is out of our (or your) control.\n\n### Sandbox\n\nIt is possible to simulate this error response by sending a request with a header of `Prefer` set to the value `code=408`.\n\nHere is an example curl request to simulate this response:\n\n```\n curl -X GET --header \"Prefer: code=408\" https://sandbox.api.service.nhs.uk/comms/\n```\n\n","content":{"application/vnd.api+json":{"schema":{"type":"object","title":"Request timeout","additionalProperties":false,"properties":{"errors":{"type":"array","minItems":1,"maxItems":1,"uniqueItems":true,"items":{"type":"object","additionalProperties":false,"properties":{"id":{"type":"string","title":"Type_ErrorIdentifier","description":"A system generated unique identifier for this request.","example":"rrt-1931948104716186917-c-geu2-10664-3111479-3.0"},"code":{"title":"Enum_Error_Timeout","type":"string","enum":["CM_TIMEOUT"],"example":"CM_TIMEOUT"},"links":{"type":"object","additionalProperties":false,"properties":{"about":{"type":"string","format":"uri","example":"https://digital.nhs.uk/developer/api-catalogue/nhs-notify","description":"https://digital.nhs.uk/developer/api-catalogue/nhs-notify"}},"minProperties":1},"status":{"type":"string","enum":["408"],"example":"408"},"title":{"type":"string","enum":["Request timeout"],"example":"Request timeout"},"detail":{"type":"string","enum":["The service was unable to receive your request within the timeout period."],"example":"The service was unable to receive your request within the timeout period."}}}}}}},"application/json":{"schema":{"type":"object","title":"Request timeout","additionalProperties":false,"properties":{"errors":{"type":"array","minItems":1,"maxItems":1,"uniqueItems":true,"items":{"type":"object","additionalProperties":false,"properties":{"id":{"type":"string","title":"Type_ErrorIdentifier","description":"A system generated unique identifier for this request.","example":"rrt-1931948104716186917-c-geu2-10664-3111479-3.0"},"code":{"title":"Enum_Error_Timeout","type":"string","enum":["CM_TIMEOUT"],"example":"CM_TIMEOUT"},"links":{"type":"object","additionalProperties":false,"properties":{"about":{"type":"string","format":"uri","example":"https://digital.nhs.uk/developer/api-catalogue/nhs-notify","description":"https://digital.nhs.uk/developer/api-catalogue/nhs-notify"}},"minProperties":1},"status":{"type":"string","enum":["408"],"example":"408"},"title":{"type":"string","enum":["Request timeout"],"example":"Request timeout"},"detail":{"type":"string","enum":["The service was unable to receive your request within the timeout period."],"example":"The service was unable to receive your request within the timeout period."}}}}}}}},"headers":{"X-Correlation-ID":{"schema":{"type":"string","pattern":"11C46F5F-CDEF-4865-94B2-0EE0EDCC26DA","description":"If the X-Correlation-ID header was included in the request the value of this header will be equal to that. Otherwise it will be a unique alphanumeric string generated by NHS Notify."}}}},"413":{"description":"This endpoint accepts a maximum of 45,000 messages per request, or a payload size of 5.2MB (whichever is the smaller). Requests containing more that 45,000 messages or exceeding the 5.2MB limit will be rejected with a HTTP 413 \"Payload too large\" status code.\n\n","content":{"application/vnd.api+json":{"schema":{"type":"object","title":"Request Entity Too Large","additionalProperties":false,"properties":{"errors":{"type":"array","minItems":1,"maxItems":1,"uniqueItems":true,"items":{"type":"object","additionalProperties":false,"properties":{"id":{"type":"string","title":"Type_ErrorIdentifier","description":"A system generated unique identifier for this request.","example":"rrt-1931948104716186917-c-geu2-10664-3111479-3.0"},"code":{"title":"Enum_Error_RequestEntityTooLarge","type":"string","enum":["CM_TOO_LARGE","CM_TOO_MANY_ITEMS"],"example":"CM_TOO_LARGE"},"links":{"type":"object","additionalProperties":false,"properties":{"about":{"type":"string","format":"uri","example":"https://digital.nhs.uk/developer/api-catalogue/nhs-notify","description":"https://digital.nhs.uk/developer/api-catalogue/nhs-notify"}},"minProperties":1},"status":{"type":"string","enum":["413"],"example":"413"},"title":{"type":"string","enum":["Request too large","Too many items"],"example":"Request too large"},"detail":{"type":"string","enum":["Request message was larger than the service limit","The property at the specified location contains too many items."],"example":"Request message was larger than the service limit"},"source":{"type":"object","additionalProperties":false,"properties":{"pointer":{"type":"string","example":"/"}}}}}}}}},"application/json":{"schema":{"type":"object","title":"Request Entity Too Large","additionalProperties":false,"properties":{"errors":{"type":"array","minItems":1,"maxItems":1,"uniqueItems":true,"items":{"type":"object","additionalProperties":false,"properties":{"id":{"type":"string","title":"Type_ErrorIdentifier","description":"A system generated unique identifier for this request.","example":"rrt-1931948104716186917-c-geu2-10664-3111479-3.0"},"code":{"title":"Enum_Error_RequestEntityTooLarge","type":"string","enum":["CM_TOO_LARGE","CM_TOO_MANY_ITEMS"],"example":"CM_TOO_LARGE"},"links":{"type":"object","additionalProperties":false,"properties":{"about":{"type":"string","format":"uri","example":"https://digital.nhs.uk/developer/api-catalogue/nhs-notify","description":"https://digital.nhs.uk/developer/api-catalogue/nhs-notify"}},"minProperties":1},"status":{"type":"string","enum":["413"],"example":"413"},"title":{"type":"string","enum":["Request too large","Too many items"],"example":"Request too large"},"detail":{"type":"string","enum":["Request message was larger than the service limit","The property at the specified location contains too many items."],"example":"Request message was larger than the service limit"},"source":{"type":"object","additionalProperties":false,"properties":{"pointer":{"type":"string","example":"/"}}}}}}}}}},"headers":{"X-Correlation-ID":{"schema":{"type":"string","pattern":"11C46F5F-CDEF-4865-94B2-0EE0EDCC26DA","description":"If the X-Correlation-ID header was included in the request the value of this header will be equal to that. Otherwise it will be a unique alphanumeric string generated by NHS Notify."}}}},"415":{"description":"The `Content-Type` of the request is not supported. This endpoint supports:\n\n* `application/json`\n* `application/vnd.api+json`\n* `application/json; charset=utf-8`\n* `application/vnd.api+json; charset=utf-8`\n","content":{"application/vnd.api+json":{"schema":{"type":"object","title":"Unsupported Media","additionalProperties":false,"properties":{"errors":{"type":"array","minItems":1,"maxItems":1,"uniqueItems":true,"items":{"type":"object","additionalProperties":false,"properties":{"id":{"type":"string","title":"Type_ErrorIdentifier","description":"A system generated unique identifier for this request.","example":"rrt-1931948104716186917-c-geu2-10664-3111479-3.0"},"code":{"title":"Enum_Error_UnsupportedMedia","type":"string","enum":["CM_UNSUPPORTED_MEDIA"],"example":"CM_UNSUPPORTED_MEDIA"},"links":{"type":"object","additionalProperties":false,"properties":{"about":{"type":"string","format":"uri","example":"https://digital.nhs.uk/developer/api-catalogue/nhs-notify","description":"https://digital.nhs.uk/developer/api-catalogue/nhs-notify"}},"minProperties":1},"status":{"type":"string","enum":["415"],"example":"415"},"title":{"type":"string","enum":["Unsupported media"],"example":"Unsupported media"},"detail":{"type":"string","enum":["Invalid content-type, this API only supports application/vnd.api+json or application/json."],"example":"Invalid content-type, this API only supports application/vnd.api+json or application/json."},"source":{"type":"object","additionalProperties":false,"properties":{"header":{"type":"string","enum":["Content-Type"],"example":"Content-Type"}}}}}}}}},"application/json":{"schema":{"type":"object","title":"Unsupported Media","additionalProperties":false,"properties":{"errors":{"type":"array","minItems":1,"maxItems":1,"uniqueItems":true,"items":{"type":"object","additionalProperties":false,"properties":{"id":{"type":"string","title":"Type_ErrorIdentifier","description":"A system generated unique identifier for this request.","example":"rrt-1931948104716186917-c-geu2-10664-3111479-3.0"},"code":{"title":"Enum_Error_UnsupportedMedia","type":"string","enum":["CM_UNSUPPORTED_MEDIA"],"example":"CM_UNSUPPORTED_MEDIA"},"links":{"type":"object","additionalProperties":false,"properties":{"about":{"type":"string","format":"uri","example":"https://digital.nhs.uk/developer/api-catalogue/nhs-notify","description":"https://digital.nhs.uk/developer/api-catalogue/nhs-notify"}},"minProperties":1},"status":{"type":"string","enum":["415"],"example":"415"},"title":{"type":"string","enum":["Unsupported media"],"example":"Unsupported media"},"detail":{"type":"string","enum":["Invalid content-type, this API only supports application/vnd.api+json or application/json."],"example":"Invalid content-type, this API only supports application/vnd.api+json or application/json."},"source":{"type":"object","additionalProperties":false,"properties":{"header":{"type":"string","enum":["Content-Type"],"example":"Content-Type"}}}}}}}}}},"headers":{"X-Correlation-ID":{"schema":{"type":"string","pattern":"11C46F5F-CDEF-4865-94B2-0EE0EDCC26DA","description":"If the X-Correlation-ID header was included in the request the value of this header will be equal to that. Otherwise it will be a unique alphanumeric string generated by NHS Notify."}}}},"422":{"description":"Request already received and it will be ignored. Note that NHS Notify retains details of your original request for up to 9 months. Duplicate submissions received after this period will still be accepted.\n\n### Sandbox\n\nIt is possible to trigger this on the sandbox by using the `Prefer` header with a value of `code=422_batch`.\n\nHere is an example curl request to trigger a `422`:\n\n```\n curl -X GET --header \"Prefer: code=422_batch\" https://sandbox.api.service.nhs.uk/comms/\n```\n","content":{"application/vnd.api+json":{"schema":{"type":"object","title":"Duplicate Request","additionalProperties":false,"properties":{"errors":{"type":"array","minItems":1,"maxItems":1,"uniqueItems":true,"items":{"type":"object","additionalProperties":false,"properties":{"id":{"type":"string","title":"Type_ErrorIdentifier","description":"A system generated unique identifier for this request.","example":"rrt-1931948104716186917-c-geu2-10664-3111479-3.0"},"code":{"title":"Enum_Error_DuplicateRequest","type":"string","enum":["CM_DUPLICATE_REQUEST"],"example":"CM_DUPLICATE_REQUEST"},"links":{"type":"object","additionalProperties":false,"properties":{"about":{"type":"string","format":"uri","example":"https://digital.nhs.uk/developer/api-catalogue/nhs-notify","description":"https://digital.nhs.uk/developer/api-catalogue/nhs-notify"}},"minProperties":1},"status":{"type":"string","enum":["422"],"example":"422"},"title":{"type":"string","example":"Duplicate batch request"},"detail":{"type":"string","example":"Request exists with identical messageBatchReference"},"source":{"type":"object","additionalProperties":false,"properties":{"pointer":{"type":"string","example":"/data/attributes/messageBatchReference"}}}}}}}}},"application/json":{"schema":{"type":"object","title":"Duplicate Request","additionalProperties":false,"properties":{"errors":{"type":"array","minItems":1,"maxItems":1,"uniqueItems":true,"items":{"type":"object","additionalProperties":false,"properties":{"id":{"type":"string","title":"Type_ErrorIdentifier","description":"A system generated unique identifier for this request.","example":"rrt-1931948104716186917-c-geu2-10664-3111479-3.0"},"code":{"title":"Enum_Error_DuplicateRequest","type":"string","enum":["CM_DUPLICATE_REQUEST"],"example":"CM_DUPLICATE_REQUEST"},"links":{"type":"object","additionalProperties":false,"properties":{"about":{"type":"string","format":"uri","example":"https://digital.nhs.uk/developer/api-catalogue/nhs-notify","description":"https://digital.nhs.uk/developer/api-catalogue/nhs-notify"}},"minProperties":1},"status":{"type":"string","enum":["422"],"example":"422"},"title":{"type":"string","example":"Duplicate batch request"},"detail":{"type":"string","example":"Request exists with identical messageBatchReference"},"source":{"type":"object","additionalProperties":false,"properties":{"pointer":{"type":"string","example":"/data/attributes/messageBatchReference"}}}}}}}}}},"headers":{"X-Correlation-ID":{"schema":{"type":"string","pattern":"11C46F5F-CDEF-4865-94B2-0EE0EDCC26DA","description":"If the X-Correlation-ID header was included in the request the value of this header will be equal to that. Otherwise it will be a unique alphanumeric string generated by NHS Notify."}}}},"425":{"description":"You have retried this request too early, the previous request is still being processed. Re-send the request after the time (in seconds) specified in the `Retry-After` header.\n\n### Sandbox\n\nIt is possible to trigger this on the sandbox by using the `Prefer` header with a value of `code=425`.\n\nHere is an example curl request to trigger a `425`:\n\n```\n curl -X GET --header \"Prefer: code=425\" https://sandbox.api.service.nhs.uk/comms/\n```\n","content":{"application/vnd.api+json":{"schema":{"type":"object","title":"Retry too early","additionalProperties":false,"properties":{"errors":{"type":"array","minItems":1,"maxItems":1,"uniqueItems":true,"items":{"type":"object","additionalProperties":false,"properties":{"id":{"type":"string","title":"Type_ErrorIdentifier","description":"A system generated unique identifier for this request.","example":"rrt-1931948104716186917-c-geu2-10664-3111479-3.0"},"code":{"title":"Enum_Error_Retry_Too_Early","type":"string","enum":["CM_RETRY_TOO_EARLY"],"example":"CM_RETRY_TOO_EARLY"},"links":{"type":"object","additionalProperties":false,"properties":{"about":{"type":"string","format":"uri","example":"https://digital.nhs.uk/developer/api-catalogue/nhs-notify","description":"https://digital.nhs.uk/developer/api-catalogue/nhs-notify"}},"minProperties":1},"status":{"type":"string","enum":["425"],"example":"425"},"title":{"type":"string","enum":["Retried too early"],"example":"Retried too early"},"detail":{"type":"string","enum":["You have retried this request too early, the previous request is still being processed. Re-send the request after the time (in seconds) specified `Retry-After` header."],"example":"You have retried this request too early, the previous request is still being processed. Re-send the request after the time (in seconds) specified `Retry-After` header."}}}}}}},"application/json":{"schema":{"type":"object","title":"Retry too early","additionalProperties":false,"properties":{"errors":{"type":"array","minItems":1,"maxItems":1,"uniqueItems":true,"items":{"type":"object","additionalProperties":false,"properties":{"id":{"type":"string","title":"Type_ErrorIdentifier","description":"A system generated unique identifier for this request.","example":"rrt-1931948104716186917-c-geu2-10664-3111479-3.0"},"code":{"title":"Enum_Error_Retry_Too_Early","type":"string","enum":["CM_RETRY_TOO_EARLY"],"example":"CM_RETRY_TOO_EARLY"},"links":{"type":"object","additionalProperties":false,"properties":{"about":{"type":"string","format":"uri","example":"https://digital.nhs.uk/developer/api-catalogue/nhs-notify","description":"https://digital.nhs.uk/developer/api-catalogue/nhs-notify"}},"minProperties":1},"status":{"type":"string","enum":["425"],"example":"425"},"title":{"type":"string","enum":["Retried too early"],"example":"Retried too early"},"detail":{"type":"string","enum":["You have retried this request too early, the previous request is still being processed. Re-send the request after the time (in seconds) specified `Retry-After` header."],"example":"You have retried this request too early, the previous request is still being processed. Re-send the request after the time (in seconds) specified `Retry-After` header."}}}}}}}},"headers":{"Retry-After":{"schema":{"type":"integer","format":"duration","minimum":300,"multipleOf":1,"example":300},"description":"Time to wait before retrying the request."},"X-Correlation-ID":{"schema":{"type":"string","pattern":"11C46F5F-CDEF-4865-94B2-0EE0EDCC26DA","description":"If the X-Correlation-ID header was included in the request the value of this header will be equal to that. Otherwise it will be a unique alphanumeric string generated by NHS Notify."}}}},"429":{"description":"You have made too many requests too quickly, you must send requests at a slower rate.\n\nIf you have a retry mechanism in your HTTP client you may want to look at implementing an [exponential backoff](https://en.wikipedia.org/wiki/Exponential_backoff) or you can use the `Retry-After` response header to determine when you should retry your request.\n\n### Sandbox\n\nIt is possible to trigger this on the sandbox by using the `Prefer` header with a value of `code=429`.\n\nHere is an example curl request to trigger a `429`:\n\n```\n curl -X GET --header \"Prefer: code=429\" https://sandbox.api.service.nhs.uk/comms/\n```\n","content":{"application/vnd.api+json":{"schema":{"type":"object","title":"Too many requests","additionalProperties":false,"properties":{"errors":{"type":"array","minItems":1,"maxItems":1,"uniqueItems":true,"items":{"type":"object","additionalProperties":false,"properties":{"id":{"type":"string","title":"Type_ErrorIdentifier","description":"A system generated unique identifier for this request.","example":"rrt-1931948104716186917-c-geu2-10664-3111479-3.0"},"code":{"title":"Enum_Error_Quota","type":"string","enum":["CM_QUOTA"],"example":"CM_QUOTA"},"links":{"type":"object","additionalProperties":false,"properties":{"about":{"type":"string","format":"uri","example":"https://digital.nhs.uk/developer/api-catalogue/nhs-notify","description":"https://digital.nhs.uk/developer/api-catalogue/nhs-notify"}},"minProperties":1},"status":{"type":"string","enum":["429"],"example":"429"},"title":{"type":"string","enum":["Too many requests"],"example":"Too many requests"},"detail":{"type":"string","enum":["You have made too many requests. Re-send the request after the time (in seconds) specified `Retry-After` header."],"example":"You have made too many requests. Re-send the request after the time (in seconds) specified `Retry-After` header."}}}}}}},"application/json":{"schema":{"type":"object","title":"Too many requests","additionalProperties":false,"properties":{"errors":{"type":"array","minItems":1,"maxItems":1,"uniqueItems":true,"items":{"type":"object","additionalProperties":false,"properties":{"id":{"type":"string","title":"Type_ErrorIdentifier","description":"A system generated unique identifier for this request.","example":"rrt-1931948104716186917-c-geu2-10664-3111479-3.0"},"code":{"title":"Enum_Error_Quota","type":"string","enum":["CM_QUOTA"],"example":"CM_QUOTA"},"links":{"type":"object","additionalProperties":false,"properties":{"about":{"type":"string","format":"uri","example":"https://digital.nhs.uk/developer/api-catalogue/nhs-notify","description":"https://digital.nhs.uk/developer/api-catalogue/nhs-notify"}},"minProperties":1},"status":{"type":"string","enum":["429"],"example":"429"},"title":{"type":"string","enum":["Too many requests"],"example":"Too many requests"},"detail":{"type":"string","enum":["You have made too many requests. Re-send the request after the time (in seconds) specified `Retry-After` header."],"example":"You have made too many requests. Re-send the request after the time (in seconds) specified `Retry-After` header."}}}}}}}},"headers":{"Retry-After":{"schema":{"type":"integer","format":"duration","minimum":5,"multipleOf":1,"example":5},"description":"Time to wait between requests in seconds"},"X-Correlation-ID":{"schema":{"type":"string","pattern":"11C46F5F-CDEF-4865-94B2-0EE0EDCC26DA","description":"If the X-Correlation-ID header was included in the request the value of this header will be equal to that. Otherwise it will be a unique alphanumeric string generated by NHS Notify."}}}},"500":{"description":"An error has occured that is stopping your request from being processed. These errors may be thrown while the system is still being configured for your use, or a misconfiguration has occurred.\n\nThe following errors can occur:\n\n| Error code | Title | Description |\n| ---------- | ----- | ----------- |\n| `CM_MISSING_ROUTING_PLAN_TEMPLATE` | Templates missing | The templates required to use the routing plan were not found. |\n| `CM_ROUTING_PLAN_DUPLICATE_TEMPLATES` | Duplicate templates | The routing plan specified contains duplicate templates. |\n| `CM_INTERNAL_SERVER_ERROR` | Error processing request | There was an internal error whilst processing this request. |\n\nWithin each error is a source object which details the location of the error within your request body.\n\nCertain errors may include an extra set of metadata to assist you with resolving the problem.\n\nThis is done using a pointer that uses the [JSON Pointer](https://datatracker.ietf.org/doc/html/rfc6901) as per the [JSON:API Error Specification](https://jsonapi.org/format/#errors).\n\n### Sandbox\n\nIt is possible to simulate these errors by sending requests with specific routing plan identifiers.\n\nTo trigger the `CM_MISSING_ROUTING_PLAN_TEMPLATE` error use routing plan id `c8857ccf-06ec-483f-9b3a-7fc732d9ad48` or `aeb16ab8-cb9c-4d23-92e9-87c78119175c`. Here is an example curl request to simulate the response:\n\n```\n curl -X POST \\\n --header \"Accept: */*\" \\\n --header \"Content-type: application/vnd.api+json\" \\\n -d '{\"data\": {\"type\": \"MessageBatch\",\"attributes\": {\"routingPlanId\": \"c8857ccf-06ec-483f-9b3a-7fc732d9ad48\",\"messageBatchReference\": \"da0b1495-c7cb-468c-9d81-07dee089d728\",\"messages\": [{\"messageReference\": \"703b8008-545d-4a04-bb90-1f2946ce1575\",\"recipient\": {\"nhsNumber\": \"9990548609\"},\"originator\": {\"odsCode\":\"X123\"},\"personalisation\": {}}]}}}' \\\n https://sandbox.api.service.nhs.uk/comms/v1/message-batches\n```\n\nTo trigger the `CM_ROUTING_PLAN_DUPLICATE_TEMPLATES` error use routing plan id `a3a4e55d-7a21-45a6-9286-8eb595c872a8`. Here is an example curl request to simulate the response:\n\n```\n curl -X POST \\\n --header \"Accept: */*\" \\\n --header \"Content-type: application/vnd.api+json\" \\\n -d '{\"data\": {\"type\": \"MessageBatch\",\"attributes\": {\"routingPlanId\": \"a3a4e55d-7a21-45a6-9286-8eb595c872a8\",\"messageBatchReference\": \"da0b1495-c7cb-468c-9d81-07dee089d728\",\"messages\": [{\"messageReference\": \"703b8008-545d-4a04-bb90-1f2946ce1575\",\"recipient\": {\"nhsNumber\": \"9990548609\"},\"originator\": {\"odsCode\":\"X123\"},\"personalisation\": {}}]}}}' \\\n https://sandbox.api.service.nhs.uk/comms/v1/message-batches\n```\n\nIt is possible to trigger the `CM_INTERNAL_SERVER_ERROR` on the sandbox by using the `Prefer` header with a value of `code=500`.\n\nHere is an example curl request to trigger a `500`:\n\n```\n curl -X GET --header \"Prefer: code=500\" https://sandbox.api.service.nhs.uk/comms/\n```\n","content":{"application/vnd.api+json":{"schema":{"type":"object","title":"Internal server error","additionalProperties":false,"properties":{"errors":{"type":"array","minItems":1,"uniqueItems":true,"items":{"type":"object","additionalProperties":false,"properties":{"id":{"type":"string","title":"Type_ErrorIdentifier","description":"A system generated unique identifier for this request.","example":"rrt-1931948104716186917-c-geu2-10664-3111479-3.0"},"code":{"title":"Enum_Error_CreateMessageInternalServerError","type":"string","enum":["CM_ROUTING_PLAN_DUPLICATE_TEMPLATES","CM_MISSING_ROUTING_PLAN_TEMPLATE","CM_INTERNAL_SERVER_ERROR"],"example":"CM_MISSING_ROUTING_PLAN_TEMPLATE"},"links":{"type":"object","additionalProperties":false,"properties":{"about":{"type":"string","format":"uri","example":"https://digital.nhs.uk/developer/api-catalogue/nhs-notify","description":"https://digital.nhs.uk/developer/api-catalogue/nhs-notify"}},"minProperties":1},"status":{"type":"string","enum":["500"],"example":"500"},"title":{"type":"string","enum":["Templates missing","Duplicate templates","Error processing request"],"example":"Templates missing"},"detail":{"type":"string","enum":["The templates required to use the routing plan were not found.","The routing plan specified contains duplicate templates.","There was an internal error whilst processing this request."],"example":"The templates required to use the routing plan were not found."},"source":{"type":"object","additionalProperties":false,"properties":{"pointer":{"type":"string","enum":["/data/attributes/routingPlanId"],"example":"/data/attributes/routingPlanId"}}}}}}}}},"application/json":{"schema":{"type":"object","title":"Internal server error","additionalProperties":false,"properties":{"errors":{"type":"array","minItems":1,"uniqueItems":true,"items":{"type":"object","additionalProperties":false,"properties":{"id":{"type":"string","title":"Type_ErrorIdentifier","description":"A system generated unique identifier for this request.","example":"rrt-1931948104716186917-c-geu2-10664-3111479-3.0"},"code":{"title":"Enum_Error_CreateMessageInternalServerError","type":"string","enum":["CM_ROUTING_PLAN_DUPLICATE_TEMPLATES","CM_MISSING_ROUTING_PLAN_TEMPLATE","CM_INTERNAL_SERVER_ERROR"],"example":"CM_MISSING_ROUTING_PLAN_TEMPLATE"},"links":{"type":"object","additionalProperties":false,"properties":{"about":{"type":"string","format":"uri","example":"https://digital.nhs.uk/developer/api-catalogue/nhs-notify","description":"https://digital.nhs.uk/developer/api-catalogue/nhs-notify"}},"minProperties":1},"status":{"type":"string","enum":["500"],"example":"500"},"title":{"type":"string","enum":["Templates missing","Duplicate templates","Error processing request"],"example":"Templates missing"},"detail":{"type":"string","enum":["The templates required to use the routing plan were not found.","The routing plan specified contains duplicate templates.","There was an internal error whilst processing this request."],"example":"The templates required to use the routing plan were not found."},"source":{"type":"object","additionalProperties":false,"properties":{"pointer":{"type":"string","enum":["/data/attributes/routingPlanId"],"example":"/data/attributes/routingPlanId"}}}}}}}}}},"headers":{"X-Correlation-ID":{"schema":{"type":"string","pattern":"11C46F5F-CDEF-4865-94B2-0EE0EDCC26DA","description":"If the X-Correlation-ID header was included in the request the value of this header will be equal to that. Otherwise it will be a unique alphanumeric string generated by NHS Notify."}}}},"503":{"description":"The service is currently not accepting requests,\n\nThis error can occur if any part of the system has gone offline.\n\n### Sandbox\n\nIt is possible to simulate this error response by sending a request with a header of `Prefer` set to the value `code=503`.\n\nHere is an example curl request to simulate this response:\n\n```\n curl -X GET --header \"Prefer: code=503\" https://sandbox.api.service.nhs.uk/comms/\n```\n","content":{"application/vnd.api+json":{"schema":{"type":"object","title":"Service unavailable","additionalProperties":false,"properties":{"errors":{"type":"array","minItems":1,"maxItems":1,"uniqueItems":true,"items":{"type":"object","additionalProperties":false,"properties":{"id":{"type":"string","title":"Type_ErrorIdentifier","description":"A system generated unique identifier for this request.","example":"rrt-1931948104716186917-c-geu2-10664-3111479-3.0"},"code":{"title":"Enum_Error_ServiceUnavailable","type":"string","enum":["CM_SERVICE_UNAVAILABLE"],"example":"CM_SERVICE_UNAVAILABLE"},"links":{"type":"object","additionalProperties":false,"properties":{"about":{"type":"string","format":"uri","example":"https://digital.nhs.uk/developer/api-catalogue/nhs-notify","description":"https://digital.nhs.uk/developer/api-catalogue/nhs-notify"}},"minProperties":1},"status":{"type":"string","enum":["503"],"example":"503"},"title":{"type":"string","enum":["The service is currently unavailable"],"example":"The service is currently unavailable"},"detail":{"type":"string","enum":["The service is currently not able to process this request, try again later."],"example":"The service is currently not able to process this request, try again later."}}}}}}},"application/json":{"schema":{"type":"object","title":"Service unavailable","additionalProperties":false,"properties":{"errors":{"type":"array","minItems":1,"maxItems":1,"uniqueItems":true,"items":{"type":"object","additionalProperties":false,"properties":{"id":{"type":"string","title":"Type_ErrorIdentifier","description":"A system generated unique identifier for this request.","example":"rrt-1931948104716186917-c-geu2-10664-3111479-3.0"},"code":{"title":"Enum_Error_ServiceUnavailable","type":"string","enum":["CM_SERVICE_UNAVAILABLE"],"example":"CM_SERVICE_UNAVAILABLE"},"links":{"type":"object","additionalProperties":false,"properties":{"about":{"type":"string","format":"uri","example":"https://digital.nhs.uk/developer/api-catalogue/nhs-notify","description":"https://digital.nhs.uk/developer/api-catalogue/nhs-notify"}},"minProperties":1},"status":{"type":"string","enum":["503"],"example":"503"},"title":{"type":"string","enum":["The service is currently unavailable"],"example":"The service is currently unavailable"},"detail":{"type":"string","enum":["The service is currently not able to process this request, try again later."],"example":"The service is currently not able to process this request, try again later."}}}}}}}},"headers":{"Retry-After":{"schema":{"type":"integer","minimum":5,"multipleOf":1,"example":5},"description":"Time to wait between requests in seconds."},"X-Correlation-ID":{"schema":{"type":"string","pattern":"11C46F5F-CDEF-4865-94B2-0EE0EDCC26DA","description":"If the X-Correlation-ID header was included in the request the value of this header will be equal to that. Otherwise it will be a unique alphanumeric string generated by NHS Notify."}}}},"504":{"description":"There is an issue communicating to our backend services. If this occurs it is a good idea to back off and retry the request at a later time - see the [Circuit Breaker pattern](https://microservices.io/patterns/reliability/circuit-breaker.html).\n\nThis error can occur if there is an issue with a dependent service and so may be bubbled up from a 3rd party HTTP call.\n\n### Sandbox\n\nIt is possible to simulate this error response by sending a request with a header of `Prefer` set to the value `code=504`.\n\nHere is an example curl request to simulate this response:\n\n```\n curl -X GET --header \"Prefer: code=504\" https://sandbox.api.service.nhs.uk/comms/\n```\n\nTo simulate a backend `504` exception bubbling upwards you can send this request:\n\n```\n curl -X GET https://sandbox.api.service.nhs.uk/comms/_timeout_504\n```\n","content":{"application/vnd.api+json":{"schema":{"type":"object","title":"Service timeout","additionalProperties":false,"properties":{"errors":{"type":"array","minItems":1,"maxItems":1,"uniqueItems":true,"items":{"type":"object","additionalProperties":false,"properties":{"id":{"type":"string","title":"Type_ErrorIdentifier","description":"A system generated unique identifier for this request.","example":"rrt-1931948104716186917-c-geu2-10664-3111479-3.0"},"code":{"title":"Enum_Error_Timeout","type":"string","enum":["CM_TIMEOUT"],"example":"CM_TIMEOUT"},"links":{"type":"object","additionalProperties":false,"properties":{"about":{"type":"string","format":"uri","example":"https://digital.nhs.uk/developer/api-catalogue/nhs-notify","description":"https://digital.nhs.uk/developer/api-catalogue/nhs-notify"}},"minProperties":1},"status":{"type":"string","enum":["504"],"example":"504"},"title":{"type":"string","enum":["Unable to call service"],"example":"Unable to call service"},"detail":{"type":"string","enum":["The downstream service has not responded within the configured timeout period."],"example":"The downstream service has not responded within the configured timeout period."}}}}}}},"application/json":{"schema":{"type":"object","title":"Service timeout","additionalProperties":false,"properties":{"errors":{"type":"array","minItems":1,"maxItems":1,"uniqueItems":true,"items":{"type":"object","additionalProperties":false,"properties":{"id":{"type":"string","title":"Type_ErrorIdentifier","description":"A system generated unique identifier for this request.","example":"rrt-1931948104716186917-c-geu2-10664-3111479-3.0"},"code":{"title":"Enum_Error_Timeout","type":"string","enum":["CM_TIMEOUT"],"example":"CM_TIMEOUT"},"links":{"type":"object","additionalProperties":false,"properties":{"about":{"type":"string","format":"uri","example":"https://digital.nhs.uk/developer/api-catalogue/nhs-notify","description":"https://digital.nhs.uk/developer/api-catalogue/nhs-notify"}},"minProperties":1},"status":{"type":"string","enum":["504"],"example":"504"},"title":{"type":"string","enum":["Unable to call service"],"example":"Unable to call service"},"detail":{"type":"string","enum":["The downstream service has not responded within the configured timeout period."],"example":"The downstream service has not responded within the configured timeout period."}}}}}}}},"headers":{"X-Correlation-ID":{"schema":{"type":"string","pattern":"11C46F5F-CDEF-4865-94B2-0EE0EDCC26DA","description":"If the X-Correlation-ID header was included in the request the value of this header will be equal to that. Otherwise it will be a unique alphanumeric string generated by NHS Notify."}}}}}}},"/v1/messages":{"post":{"summary":"Send a single message","description":"## Overview\n\nUse this endpoint to send a single message to an NHS patient.\n\n### References\n\nYou must provide a single reference value within the payload to this endpoint that is a message reference.\n\nThe message reference (`messageReference`) needs to be unique across all single messages you have sent. This value is used to store your reference for this specific message and can be used if you lose (or do not recieve) our unique identifier in the response.\n\n### Personalisation\n\nYou may be required to send through specific personalisation fields based upon the routing plan (`routingPlanId`). These will have been setup during your onboarding process.\n\nThese are not validated when we store your message, but will be validated when we attempt to send the message according to the routing plan. If there are values missing from this then the message will fail to send.\n\n### Sandbox\n\nWhen sending this request on sandbox you must use one of the 6 preconfigured routing plan identifiers:\n\n- `b838b13c-f98c-4def-93f0-515d4e4f4ee1`\n- `49e43b98-70cb-47a9-a55e-fe70c9a6f77c`\n- `b402cd20-b62a-4357-8e02-2952959531c8`\n- `936e9d45-15de-4a95-bb36-ae163c33ae53`\n- `9ba00d23-cd6f-4aca-8688-00abc85a7980`\n- `00000000-0000-0000-0000-000000000001`\n\nOn other environments these values will be established as part of your [NHS Notify onboarding](#overview--onboarding).\n\nHere is an example curl request which creates a message using one of these routing plan identifiers:\n\n```\n curl -X POST \\\n --header \"Accept: */*\" \\\n --header \"Content-type: application/vnd.api+json\" \\\n -d '{\"data\": {\"type\": \"Message\",\"attributes\": {\"routingPlanId\": \"b838b13c-f98c-4def-93f0-515d4e4f4ee1\",\"messageReference\": \"da0b1495-c7cb-468c-9d81-07dee089d728\",\"recipient\": {\"nhsNumber\": \"9990548609\"},\"originator\": {\"odsCode\":\"X123\"},\"personalisation\": {}}}}' \\\n https://sandbox.api.service.nhs.uk/comms/v1/messages\n```\n","operationId":"create-message","parameters":[{"name":"Authorization","in":"header","description":"An [OAuth 2.0 bearer token](https://digital.nhs.uk/developer/guides-and-documentation/security-and-authorisation/application-restricted-restful-apis-signed-jwt-authentication).\nRequired in all environments except sandbox.","schema":{"type":"string","format":"^Bearer [[:ascii:]]+$","example":"Bearer g1112R_ccQ1Ebbb4gtHBP1aaaNM"}},{"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.","schema":{"type":"string","example":"11C46F5F-CDEF-4865-94B2-0EE0EDCC26DA"}}],"requestBody":{"description":"","content":{"application/vnd.api+json":{"schema":{"title":"CreateMessage","type":"object","properties":{"data":{"type":"object","properties":{"type":{"title":"Enum_Message","type":"string","enum":["Message"],"example":"Message"},"attributes":{"type":"object","required":["routingPlanId","messageReference","recipient"],"properties":{"routingPlanId":{"type":"string","format":"uuid","description":"This is the routing plan you wish your message to be sent with. The values available to you for this are setup during your [onboarding process](#overview--onboarding).\n\nThere are also some global routingPlanIds available, please see the [Free-text communications documentation](#section/Free-text-communications).\n\nIf you send through an invalid routing plan id you will receive a 404 response.","example":"b838b13c-f98c-4def-93f0-515d4e4f4ee1"},"messageReference":{"type":"string","description":"This is a client-supplied unique reference for this message.\n\nThis value is used internally to de-duplicate messages. If you send the same value through multiple times only one of the requests will be actioned.","example":"da0b1495-c7cb-468c-9d81-07dee089d728"},"billingReference":{"type":"string","description":"Optional reference for billing purposes. Can be any string.","example":"billing-ref-1"},"recipient":{"type":"object","title":"Recipient","additionalProperties":false,"properties":{"nhsNumber":{"type":"string","pattern":"^\\d{10}$","minLength":10,"maxLength":10,"example":"9990548609","description":"The [NHS number](https://digital.nhs.uk/services/nhs-number) of the recipient. Only [valid NHS Numbers](https://www.datadictionary.nhs.uk/attributes/nhs_number.html) will be accepted. This will be used to lookup the recipients details with the [Personal Demographics Service](https://digital.nhs.uk/developer/api-catalogue/personal-demographics-service-fhir). Normally a required field, unless prior agreement with the Onboarding team is in place."},"contactDetails":{"type":"object","description":"Overriding contact details is a sensitive action and requires explicit approval from the onboarding team.","properties":{"email":{"type":"string","pattern":"[A-Za-z0-9._%+-]+@[A-Za-z0-9.-]+\\.[A-Z|a-z]{2,}","minLength":6,"maxLength":90,"description":"Overriding email address for recipient.","example":"recipient@nhs.net"},"sms":{"type":"string","description":"Overriding mobile number for the recipient. Must be in a valid UK format or international format with a country code.\n\nLearn more about [sending text messages to international numbers](https://notify.nhs.uk/pricing/text-messages#sending-text-messages-to-international-numbers).\n","example":"07777777777"},"address":{"type":"object","description":"Overriding address.","properties":{"lines":{"type":"array","minItems":2,"maxItems":5,"description":"Lines of overriding address.","items":{"type":"string"},"example":["NHS England","6th Floor","7&8 Wellington Place","Leeds","West Yorkshire"]},"postcode":{"type":"string","description":"Postcode of overriding address. A required field when address is specified. Must be a valid UK postcode format.","example":"LS1 4AP"}}},"name":{"type":"object","description":"Overriding name fields for the recipient.","properties":{"prefix":{"type":"string","description":"Prefix of overriding name.","example":"Dr."},"firstName":{"type":"string","description":"First name of overriding name.","example":"John"},"middleNames":{"type":"string","description":"Middle names of overriding name.","example":"Andrew Robert"},"lastName":{"type":"string","description":"Last name of overriding name. A required field when name is specified.","example":"Smith"},"suffix":{"type":"string","description":"Suffix of overriding name.","example":"Jr."}}}}}}},"originator":{"type":"object","title":"Originator","additionalProperties":false,"properties":{"odsCode":{"type":"string","description":"ODS code used to identify the sender when using the NHS App channel (allowOdsOverride must be enabled on the corresponding NHS Notify client).","example":"X26"}}},"personalisation":{"type":"object","description":"The personalisation keys and values for this message. These are linked to the routingPlanId provided and are agreed upon during [onboarding](#overview--onboarding)."}}}},"required":["type","attributes"]}},"required":["data"]}},"application/json":{"schema":{"title":"CreateMessage","type":"object","properties":{"data":{"type":"object","properties":{"type":{"title":"Enum_Message","type":"string","enum":["Message"],"example":"Message"},"attributes":{"type":"object","required":["routingPlanId","messageReference","recipient"],"properties":{"routingPlanId":{"type":"string","format":"uuid","description":"This is the routing plan you wish your message to be sent with. The values available to you for this are setup during your [onboarding process](#overview--onboarding).\n\nThere are also some global routingPlanIds available, please see the [Free-text communications documentation](#section/Free-text-communications).\n\nIf you send through an invalid routing plan id you will receive a 404 response.","example":"b838b13c-f98c-4def-93f0-515d4e4f4ee1"},"messageReference":{"type":"string","description":"This is a client-supplied unique reference for this message.\n\nThis value is used internally to de-duplicate messages. If you send the same value through multiple times only one of the requests will be actioned.","example":"da0b1495-c7cb-468c-9d81-07dee089d728"},"billingReference":{"type":"string","description":"Optional reference for billing purposes. Can be any string.","example":"billing-ref-1"},"recipient":{"type":"object","title":"Recipient","additionalProperties":false,"properties":{"nhsNumber":{"type":"string","pattern":"^\\d{10}$","minLength":10,"maxLength":10,"example":"9990548609","description":"The [NHS number](https://digital.nhs.uk/services/nhs-number) of the recipient. Only [valid NHS Numbers](https://www.datadictionary.nhs.uk/attributes/nhs_number.html) will be accepted. This will be used to lookup the recipients details with the [Personal Demographics Service](https://digital.nhs.uk/developer/api-catalogue/personal-demographics-service-fhir). Normally a required field, unless prior agreement with the Onboarding team is in place."},"contactDetails":{"type":"object","description":"Overriding contact details is a sensitive action and requires explicit approval from the onboarding team.","properties":{"email":{"type":"string","pattern":"[A-Za-z0-9._%+-]+@[A-Za-z0-9.-]+\\.[A-Z|a-z]{2,}","minLength":6,"maxLength":90,"description":"Overriding email address for recipient.","example":"recipient@nhs.net"},"sms":{"type":"string","description":"Overriding mobile number for the recipient. Must be in a valid UK format or international format with a country code.\n\nLearn more about [sending text messages to international numbers](https://notify.nhs.uk/pricing/text-messages#sending-text-messages-to-international-numbers).\n","example":"07777777777"},"address":{"type":"object","description":"Overriding address.","properties":{"lines":{"type":"array","minItems":2,"maxItems":5,"description":"Lines of overriding address.","items":{"type":"string"},"example":["NHS England","6th Floor","7&8 Wellington Place","Leeds","West Yorkshire"]},"postcode":{"type":"string","description":"Postcode of overriding address. A required field when address is specified. Must be a valid UK postcode format.","example":"LS1 4AP"}}},"name":{"type":"object","description":"Overriding name fields for the recipient.","properties":{"prefix":{"type":"string","description":"Prefix of overriding name.","example":"Dr."},"firstName":{"type":"string","description":"First name of overriding name.","example":"John"},"middleNames":{"type":"string","description":"Middle names of overriding name.","example":"Andrew Robert"},"lastName":{"type":"string","description":"Last name of overriding name. A required field when name is specified.","example":"Smith"},"suffix":{"type":"string","description":"Suffix of overriding name.","example":"Jr."}}}}}}},"originator":{"type":"object","title":"Originator","additionalProperties":false,"properties":{"odsCode":{"type":"string","description":"ODS code used to identify the sender when using the NHS App channel (allowOdsOverride must be enabled on the corresponding NHS Notify client).","example":"X26"}}},"personalisation":{"type":"object","description":"The personalisation keys and values for this message. These are linked to the routingPlanId provided and are agreed upon during [onboarding](#overview--onboarding)."}}}},"required":["type","attributes"]}},"required":["data"]}}}},"responses":{"201":{"description":"Your message has been created. The backend service will process the message according to the routing plan identified in the request.\n\nThe response includes both your `messageReference` and our message `id`. You should store the `id` in your database.\n","content":{"application/vnd.api+json":{"schema":{"type":"object","title":"Message response","additionalProperties":false,"properties":{"data":{"type":"object","additionalProperties":false,"required":["type","id","attributes","links"],"properties":{"type":{"title":"Enum_Message","type":"string","enum":["Message"],"example":"Message"},"id":{"description":"Identifier for this Message. You should store this identifier for later lookups.","type":"string","title":"Type_KSUID","pattern":"^[a-zA-Z0-9]{27}$","minLength":27,"maxLength":27,"example":"2WL3qFTEFM0qMY8xjRbt1LIKCzM"},"attributes":{"type":"object","additionalProperties":false,"required":["messageReference","messageStatus","timestamps","routingPlan"],"properties":{"messageReference":{"type":"string","description":"Your unique message reference, provided within the payload to create this message.","example":"da0b1495-c7cb-468c-9d81-07dee089d728"},"messageStatus":{"description":"The status of your message.","title":"Enum_MessageCreatedStatus","type":"string","enum":["created"],"example":"created"},"timestamps":{"type":"object","additionalProperties":false,"required":["created"],"properties":{"created":{"type":"string","description":"The date and time that your message was created at.","format":"date-time","example":"2023-11-17T14:27:51.413Z"}}},"routingPlan":{"description":"The routing plan that you requested the message be sent with.","type":"object","additionalProperties":false,"required":["id","name","createdDate"],"properties":{"id":{"type":"string","format":"uuid","description":"The identifier for the routing plan.","example":"b838b13c-f98c-4def-93f0-515d4e4f4ee1"},"name":{"type":"string","description":"The name of the routing plan.","example":"Plan Abc"},"version":{"type":"string","description":"This identifies the specific version of the routing plan.","example":"ztoe2qRAM8M8vS0bqajhyEBcvXacrGPp"},"createdDate":{"type":"string","description":"The creation date of the routing plan.","format":"date-time","example":"2023-11-17T14:27:51.413Z"}}}}},"links":{"type":"object","additionalProperties":false,"description":"Contains links to related objects.","required":["self"],"properties":{"self":{"type":"string","format":"uri","description":"URI of this message.","example":"https://api.service.nhs.uk/comms/v1/messages/2WL3qFTEFM0qMY8xjRbt1LIKCzM"}}}}}}}},"application/json":{"schema":{"type":"object","title":"Message response","additionalProperties":false,"properties":{"data":{"type":"object","additionalProperties":false,"required":["type","id","attributes","links"],"properties":{"type":{"title":"Enum_Message","type":"string","enum":["Message"],"example":"Message"},"id":{"description":"Identifier for this Message. You should store this identifier for later lookups.","type":"string","title":"Type_KSUID","pattern":"^[a-zA-Z0-9]{27}$","minLength":27,"maxLength":27,"example":"2WL3qFTEFM0qMY8xjRbt1LIKCzM"},"attributes":{"type":"object","additionalProperties":false,"required":["messageReference","messageStatus","timestamps","routingPlan"],"properties":{"messageReference":{"type":"string","description":"Your unique message reference, provided within the payload to create this message.","example":"da0b1495-c7cb-468c-9d81-07dee089d728"},"messageStatus":{"description":"The status of your message.","title":"Enum_MessageCreatedStatus","type":"string","enum":["created"],"example":"created"},"timestamps":{"type":"object","additionalProperties":false,"required":["created"],"properties":{"created":{"type":"string","description":"The date and time that your message was created at.","format":"date-time","example":"2023-11-17T14:27:51.413Z"}}},"routingPlan":{"description":"The routing plan that you requested the message be sent with.","type":"object","additionalProperties":false,"required":["id","name","createdDate"],"properties":{"id":{"type":"string","format":"uuid","description":"The identifier for the routing plan.","example":"b838b13c-f98c-4def-93f0-515d4e4f4ee1"},"name":{"type":"string","description":"The name of the routing plan.","example":"Plan Abc"},"version":{"type":"string","description":"This identifies the specific version of the routing plan.","example":"ztoe2qRAM8M8vS0bqajhyEBcvXacrGPp"},"createdDate":{"type":"string","description":"The creation date of the routing plan.","format":"date-time","example":"2023-11-17T14:27:51.413Z"}}}}},"links":{"type":"object","additionalProperties":false,"description":"Contains links to related objects.","required":["self"],"properties":{"self":{"type":"string","format":"uri","description":"URI of this message.","example":"https://api.service.nhs.uk/comms/v1/messages/2WL3qFTEFM0qMY8xjRbt1LIKCzM"}}}}}}}}},"headers":{"X-Correlation-ID":{"schema":{"type":"string","pattern":"11C46F5F-CDEF-4865-94B2-0EE0EDCC26DA","description":"If the X-Correlation-ID header was included in the request the value of this header will be equal to that. Otherwise it will be a unique alphanumeric string generated by NHS Notify."}},"Location":{"schema":{"type":"string","example":"https://api.service.nhs.uk/comms/v1/messages/0ujsszwN8NRY24YaXiTIE2VWDTS"}}}},"400":{"description":"A validation error has occurred with the request body sent. Up to 100 validation errors will be returned, if there are more than 100 validation errors then the first 100 will be returned.\n\nThe following validation errors can occur:\n\n| Error code | Title | Description |\n| ---------- | ----- | ----------- |\n| `CM_MISSING_VALUE` | Missing property | The property at the specified location is required, but was not present in the request. |\n| `CM_NULL_VALUE` | Property cannot be null | The property at the specified location is required, but a null value was passed in the request. |\n| `CM_INVALID_VALUE` | Invalid value | The property at the specified location does not allow this value. |\n| `CM_INVALID_NHS_NUMBER` | Invalid nhs number | The value provided in this nhsNumber field is not a valid NHS number. |\n| `CM_ODS_CODE_REQUIRED` | Originator odsCode must be provided | An originator with odsCode must be provided, as your account does not have a default ODS code. |\n| `CM_CANNOT_SET_ODS_CODE` | Cannot set ODS code | Your account is not permitted to set originator ODS codes. |\n| `CM_CANNOT_SET_CONTACT_DETAILS` | Cannot set contact details | Your account is not allowed to provide alternative contact details. |\n\nWithin each error is a source object which details the location of the error within your request body.\n\nThis is done using a pointer that uses the [JSON Pointer](https://datatracker.ietf.org/doc/html/rfc6901) as per the [JSON:API Error Specification](https://jsonapi.org/format/#errors).\n\n### Sandbox\n\nIt is possible to trigger some of the errors in the sandbox by sending the header `Authorization` with certain values.\n\nHere is an example curl request to trigger a `CM_CANNOT_SET_ODS_CODE`:\n\n```\n curl -X POST \\\n --header \"Accept: */*\" \\\n --header \"Content-type: application/vnd.api+json\" \\\n --header \"Authorization: noOdsChange\" \\\n -d '{\"data\": {\"type\": \"Message\",\"attributes\": {\"routingPlanId\": \"b838b13c-f98c-4def-93f0-515d4e4f4ee1\",\"messageReference\": \"da0b1495-c7cb-468c-9d81-07dee089d728\",\"recipient\": {\"nhsNumber\": \"9990548609\"},\"originator\": {\"odsCode\":\"X123\"},\"personalisation\": {}}}}' \\\n https://sandbox.api.service.nhs.uk/comms/v1/messages\n```\n\nHere is an example curl request to trigger a `CM_CANNOT_SET_CONTACT_DETAILS`:\n\n```\n curl -X POST \\\n --header \"Accept: */*\" \\\n --header \"Content-type: application/vnd.api+json\" \\\n --header \"Authorization: notAllowedContactDetailOverride\" \\\n -d '{\"data\": {\"type\": \"Message\",\"attributes\": {\"routingPlanId\": \"b838b13c-f98c-4def-93f0-515d4e4f4ee1\",\"messageReference\": \"da0b1495-c7cb-468c-9d81-07dee089d728\",\"recipient\": {\"nhsNumber\": \"9990548609\",\"contactDetails\": {\"sms\": \"07777000000\"}},\"personalisation\": {}}}}' \\\n https://sandbox.api.service.nhs.uk/comms/v1/messages\n```\n","content":{"application/vnd.api+json":{"schema":{"type":"object","title":"Request not processable","additionalProperties":false,"properties":{"errors":{"type":"array","minItems":1,"uniqueItems":true,"items":{"type":"object","additionalProperties":false,"properties":{"id":{"type":"string","title":"Type_ErrorIdentifier","description":"A system generated unique identifier for this request.","example":"rrt-1931948104716186917-c-geu2-10664-3111479-3.0"},"code":{"title":"Enum_ErrorCode","type":"string","enum":["CM_MISSING_VALUE","CM_NULL_VALUE","CM_INVALID_VALUE","CM_INVALID_NHS_NUMBER","CM_DUPLICATE_VALUE","CM_TOO_FEW_ITEMS","CM_ODS_CODE_REQUIRED","CM_CANNOT_SET_ODS_CODE"],"example":"CM_INVALID_NHS_NUMBER"},"links":{"type":"object","additionalProperties":false,"properties":{"about":{"type":"string","format":"uri","example":"https://digital.nhs.uk/developer/api-catalogue/nhs-notify","description":"https://digital.nhs.uk/developer/api-catalogue/nhs-notify"},"nhsNumbers":{"type":"string","format":"uri","example":"https://www.datadictionary.nhs.uk/attributes/nhs_number.html","description":"https://www.datadictionary.nhs.uk/attributes/nhs_number.html This link is only provided in the instance of a \"CM_INVALID_NHS_NUMBER\" error."}},"minProperties":1},"status":{"type":"string","enum":["400"],"example":"400"},"title":{"type":"string","title":"Enum_Title","description":"The title of this error response.","enum":["Missing property","Property cannot be null","Invalid value","Duplicate value","Too few items","Invalid nhs number","Originator odsCode must be provided","Cannot set ODS code"],"example":"Invalid nhs number"},"detail":{"type":"string","description":"A human-readable description of the error.","example":"The value provided in this nhsNumber field is not a valid NHS number."},"source":{"type":"object","additionalProperties":false,"properties":{"pointer":{"type":"string","description":"Indicates the path to the field in the request where the validation error occurred.","example":"/data/attributes/recipient/nhsNumber"}}}}}}}}},"application/json":{"schema":{"type":"object","title":"Request not processable","additionalProperties":false,"properties":{"errors":{"type":"array","minItems":1,"uniqueItems":true,"items":{"type":"object","additionalProperties":false,"properties":{"id":{"type":"string","title":"Type_ErrorIdentifier","description":"A system generated unique identifier for this request.","example":"rrt-1931948104716186917-c-geu2-10664-3111479-3.0"},"code":{"title":"Enum_ErrorCode","type":"string","enum":["CM_MISSING_VALUE","CM_NULL_VALUE","CM_INVALID_VALUE","CM_INVALID_NHS_NUMBER","CM_DUPLICATE_VALUE","CM_TOO_FEW_ITEMS","CM_ODS_CODE_REQUIRED","CM_CANNOT_SET_ODS_CODE"],"example":"CM_INVALID_NHS_NUMBER"},"links":{"type":"object","additionalProperties":false,"properties":{"about":{"type":"string","format":"uri","example":"https://digital.nhs.uk/developer/api-catalogue/nhs-notify","description":"https://digital.nhs.uk/developer/api-catalogue/nhs-notify"},"nhsNumbers":{"type":"string","format":"uri","example":"https://www.datadictionary.nhs.uk/attributes/nhs_number.html","description":"https://www.datadictionary.nhs.uk/attributes/nhs_number.html This link is only provided in the instance of a \"CM_INVALID_NHS_NUMBER\" error."}},"minProperties":1},"status":{"type":"string","enum":["400"],"example":"400"},"title":{"type":"string","title":"Enum_Title","description":"The title of this error response.","enum":["Missing property","Property cannot be null","Invalid value","Duplicate value","Too few items","Invalid nhs number","Originator odsCode must be provided","Cannot set ODS code"],"example":"Invalid nhs number"},"detail":{"type":"string","description":"A human-readable description of the error.","example":"The value provided in this nhsNumber field is not a valid NHS number."},"source":{"type":"object","additionalProperties":false,"properties":{"pointer":{"type":"string","description":"Indicates the path to the field in the request where the validation error occurred.","example":"/data/attributes/recipient/nhsNumber"}}}}}}}}}},"headers":{"X-Correlation-ID":{"schema":{"type":"string","pattern":"11C46F5F-CDEF-4865-94B2-0EE0EDCC26DA","description":"If the X-Correlation-ID header was included in the request the value of this header will be equal to that. Otherwise it will be a unique alphanumeric string generated by NHS Notify."}}}},"401":{"description":"Your request was not authorized - you need to send a `Authorization` header with a valid `Bearer` token.\n\nSee the documentation on [how to generate a valid token](https://digital.nhs.uk/developer/guides-and-documentation/security-and-authorisation/application-restricted-restful-apis-signed-jwt-authentication).\n\n### Sandbox\n\nIt is possible to trigger this error in the sandbox by sending the header `Prefer` with a value of `code=401`.\n\nHere is an example curl request to trigger a `401`:\n\n```\n curl -X GET \\\n --header \"Accept: */*\" \\\n --header \"Prefer: code=401\" \\\n https://sandbox.api.service.nhs.uk/comms/\n```\n","content":{"application/vnd.api+json":{"schema":{"type":"object","title":"Access Denied","additionalProperties":false,"properties":{"errors":{"type":"array","minItems":1,"maxItems":1,"uniqueItems":true,"items":{"type":"object","additionalProperties":false,"properties":{"id":{"type":"string","title":"Type_ErrorIdentifier","description":"A system generated unique identifier for this request.","example":"rrt-1931948104716186917-c-geu2-10664-3111479-3.0"},"code":{"title":"Enum_Error_AccessDenied","type":"string","enum":["CM_DENIED"],"example":"CM_DENIED"},"links":{"type":"object","additionalProperties":false,"properties":{"about":{"type":"string","format":"uri","example":"https://digital.nhs.uk/developer/api-catalogue/nhs-notify","description":"https://digital.nhs.uk/developer/api-catalogue/nhs-notify"}},"minProperties":1},"status":{"type":"string","enum":["401"],"example":"401"},"title":{"type":"string","enum":["Access denied"],"example":"Access denied"},"detail":{"type":"string","enum":["Access token missing, invalid or expired, or calling application not configured for this operation."],"example":"Access token missing, invalid or expired, or calling application not configured for this operation."},"source":{"type":"object","additionalProperties":false,"properties":{"header":{"type":"string","enum":["Authorization"],"example":"Authorization"}}}}}}}}},"application/json":{"schema":{"type":"object","title":"Access Denied","additionalProperties":false,"properties":{"errors":{"type":"array","minItems":1,"maxItems":1,"uniqueItems":true,"items":{"type":"object","additionalProperties":false,"properties":{"id":{"type":"string","title":"Type_ErrorIdentifier","description":"A system generated unique identifier for this request.","example":"rrt-1931948104716186917-c-geu2-10664-3111479-3.0"},"code":{"title":"Enum_Error_AccessDenied","type":"string","enum":["CM_DENIED"],"example":"CM_DENIED"},"links":{"type":"object","additionalProperties":false,"properties":{"about":{"type":"string","format":"uri","example":"https://digital.nhs.uk/developer/api-catalogue/nhs-notify","description":"https://digital.nhs.uk/developer/api-catalogue/nhs-notify"}},"minProperties":1},"status":{"type":"string","enum":["401"],"example":"401"},"title":{"type":"string","enum":["Access denied"],"example":"Access denied"},"detail":{"type":"string","enum":["Access token missing, invalid or expired, or calling application not configured for this operation."],"example":"Access token missing, invalid or expired, or calling application not configured for this operation."},"source":{"type":"object","additionalProperties":false,"properties":{"header":{"type":"string","enum":["Authorization"],"example":"Authorization"}}}}}}}}}},"headers":{"X-Correlation-ID":{"schema":{"type":"string","pattern":"11C46F5F-CDEF-4865-94B2-0EE0EDCC26DA","description":"If the X-Correlation-ID header was included in the request the value of this header will be equal to that. Otherwise it will be a unique alphanumeric string generated by NHS Notify."}}}},"403":{"description":"Your request contained an authentic bearer token in the `Authorization` header but you are not authorized to make the request.\n\nIf the error code in the response is `CM_FORBIDDEN` then this could be due to the onboarding process not having been completed. Refer to our [onboarding](#overview--onboarding) section for more information.\n\nIf the response contains the error `CM_SERVICE_BAN` then there is a ban in effect on your account.\n\n### Sandbox\n\nIt is possible to trigger the `CM_FORBIDDEN` error in the sandbox by sending the header `Prefer` with a value of `code=403`.\n\nHere is an example curl request to trigger a `CM_FORBIDDEN`:\n\n```\n curl -X GET \\\n --header \"Accept: */*\" \\\n --header \"Prefer: code=403\" \\\n https://sandbox.api.service.nhs.uk/comms/\n```\n\nTo trigger the `CM_SERVICE_BAN` error in the sandbox by sending the header `Prefer` with a value of `code=403.1`.\n\nHere is an example curl request to trigger a `CM_SERVICE_BAN`:\n\n```\n curl -X GET \\\n --header \"Accept: */*\" \\\n --header \"Prefer: code=403.1\" \\\n https://sandbox.api.service.nhs.uk/comms/\n```\n","content":{"application/vnd.api+json":{"schema":{"type":"object","title":"Forbidden","additionalProperties":false,"properties":{"errors":{"type":"array","minItems":1,"maxItems":1,"uniqueItems":true,"items":{"type":"object","additionalProperties":false,"properties":{"id":{"type":"string","title":"Type_ErrorIdentifier","description":"A system generated unique identifier for this request.","example":"rrt-1931948104716186917-c-geu2-10664-3111479-3.0"},"code":{"title":"Enum_Error_Forbidden","type":"string","enum":["CM_FORBIDDEN","CM_SERVICE_BAN"],"example":"CM_FORBIDDEN"},"links":{"type":"object","additionalProperties":false,"properties":{"about":{"type":"string","format":"uri","example":"https://digital.nhs.uk/developer/api-catalogue/nhs-notify","description":"https://digital.nhs.uk/developer/api-catalogue/nhs-notify"}},"minProperties":1},"status":{"type":"string","enum":["403"],"example":"403"},"title":{"type":"string","enum":["Forbidden","Service ban in effect"],"example":"Forbidden"},"detail":{"type":"string","enum":["Client not recognised or not yet onboarded.","A service ban is in effect on your account."],"example":"Client not recognised or not yet onboarded."},"source":{"type":"object","additionalProperties":false,"properties":{"header":{"type":"string","enum":["Authorization"],"example":"Authorization"}}}}}}}}},"application/json":{"schema":{"type":"object","title":"Forbidden","additionalProperties":false,"properties":{"errors":{"type":"array","minItems":1,"maxItems":1,"uniqueItems":true,"items":{"type":"object","additionalProperties":false,"properties":{"id":{"type":"string","title":"Type_ErrorIdentifier","description":"A system generated unique identifier for this request.","example":"rrt-1931948104716186917-c-geu2-10664-3111479-3.0"},"code":{"title":"Enum_Error_Forbidden","type":"string","enum":["CM_FORBIDDEN","CM_SERVICE_BAN"],"example":"CM_FORBIDDEN"},"links":{"type":"object","additionalProperties":false,"properties":{"about":{"type":"string","format":"uri","example":"https://digital.nhs.uk/developer/api-catalogue/nhs-notify","description":"https://digital.nhs.uk/developer/api-catalogue/nhs-notify"}},"minProperties":1},"status":{"type":"string","enum":["403"],"example":"403"},"title":{"type":"string","enum":["Forbidden","Service ban in effect"],"example":"Forbidden"},"detail":{"type":"string","enum":["Client not recognised or not yet onboarded.","A service ban is in effect on your account."],"example":"Client not recognised or not yet onboarded."},"source":{"type":"object","additionalProperties":false,"properties":{"header":{"type":"string","enum":["Authorization"],"example":"Authorization"}}}}}}}}}},"headers":{"X-Correlation-ID":{"schema":{"type":"string","pattern":"11C46F5F-CDEF-4865-94B2-0EE0EDCC26DA","description":"If the X-Correlation-ID header was included in the request the value of this header will be equal to that. Otherwise it will be a unique alphanumeric string generated by NHS Notify."}}}},"404":{"description":"The routing plan identifier passed in the body has not been found.\n\nWhen you [onboarded](#overview--onboarding) onto the service a number of valid routing plan identifiers were issued to you. You must use one of these valid routing plan identifiers when requesting for a message to be sent.\n\n### Sandbox\n\nOn the sandbox environment there are 5 valid routing plan identifiers that can be used by anybody calling the API. These are:\n\n* `b838b13c-f98c-4def-93f0-515d4e4f4ee1`\n* `49e43b98-70cb-47a9-a55e-fe70c9a6f77c`\n* `b402cd20-b62a-4357-8e02-2952959531c8`\n* `936e9d45-15de-4a95-bb36-ae163c33ae53`\n* `9ba00d23-cd6f-4aca-8688-00abc85a7980`\n\nIf you use a routing plan id that is not in this list then a `404 Not Found` error response will be triggered.\n\nOn other environments these values will be established as part of your [NHS Notify onboarding](#overview--onboarding).\n\nHere is an example curl request to trigger a `404`:\n\n```\n curl -X POST \\\n --header \"Accept: */*\" \\\n --header \"Content-type: application/vnd.api+json\" \\\n -d '{\"data\": {\"type\": \"Message\",\"attributes\": {\"routingPlanId\": \"868796f9-7ce3-4730-9f1e-23aa766edea3\",\"messageReference\": \"da0b1495-c7cb-468c-9d81-07dee089d728\",\"recipient\": {\"nhsNumber\": \"9990548609\"},\"originator\": {\"odsCode\":\"X123\"},\"personalisation\": {}}}}' \\\n https://sandbox.api.service.nhs.uk/comms/v1/messages\n```\n","content":{"application/vnd.api+json":{"schema":{"type":"object","title":"No such routing plan","additionalProperties":false,"properties":{"errors":{"type":"array","minItems":1,"maxItems":1,"uniqueItems":true,"items":{"type":"object","additionalProperties":false,"properties":{"id":{"type":"string","title":"Type_ErrorIdentifier","description":"A system generated unique identifier for this request.","example":"rrt-1931948104716186917-c-geu2-10664-3111479-3.0"},"code":{"title":"Enum_Error_NoSuchRoutingPlan","type":"string","enum":["CM_NO_SUCH_ROUTING_PLAN"],"example":"CM_NO_SUCH_ROUTING_PLAN"},"links":{"type":"object","additionalProperties":false,"properties":{"about":{"type":"string","format":"uri","example":"https://digital.nhs.uk/developer/api-catalogue/nhs-notify","description":"https://digital.nhs.uk/developer/api-catalogue/nhs-notify"}},"minProperties":1},"status":{"type":"string","enum":["404"],"example":"404"},"title":{"type":"string","enum":["No such routing plan"],"example":"No such routing plan"},"detail":{"type":"string","enum":["The routing plan specified either does not exist or is not in a usable state."],"example":"The routing plan specified either does not exist or is not in a usable state."},"source":{"type":"object","properties":{"pointer":{"type":"string","enum":["/data/attributes/routingPlan"],"example":"/data/attributes/routingPlan"}}}}}}}}},"application/json":{"schema":{"type":"object","title":"No such routing plan","additionalProperties":false,"properties":{"errors":{"type":"array","minItems":1,"maxItems":1,"uniqueItems":true,"items":{"type":"object","additionalProperties":false,"properties":{"id":{"type":"string","title":"Type_ErrorIdentifier","description":"A system generated unique identifier for this request.","example":"rrt-1931948104716186917-c-geu2-10664-3111479-3.0"},"code":{"title":"Enum_Error_NoSuchRoutingPlan","type":"string","enum":["CM_NO_SUCH_ROUTING_PLAN"],"example":"CM_NO_SUCH_ROUTING_PLAN"},"links":{"type":"object","additionalProperties":false,"properties":{"about":{"type":"string","format":"uri","example":"https://digital.nhs.uk/developer/api-catalogue/nhs-notify","description":"https://digital.nhs.uk/developer/api-catalogue/nhs-notify"}},"minProperties":1},"status":{"type":"string","enum":["404"],"example":"404"},"title":{"type":"string","enum":["No such routing plan"],"example":"No such routing plan"},"detail":{"type":"string","enum":["The routing plan specified either does not exist or is not in a usable state."],"example":"The routing plan specified either does not exist or is not in a usable state."},"source":{"type":"object","properties":{"pointer":{"type":"string","enum":["/data/attributes/routingPlan"],"example":"/data/attributes/routingPlan"}}}}}}}}}},"headers":{"X-Correlation-ID":{"schema":{"type":"string","pattern":"11C46F5F-CDEF-4865-94B2-0EE0EDCC26DA","description":"If the X-Correlation-ID header was included in the request the value of this header will be equal to that. Otherwise it will be a unique alphanumeric string generated by NHS Notify."}}}},"405":{"description":"Your request specified a method that was not allowed on this endpoint.\n\nEndpoints only allow certain methods to be called on them. If your method was not one of the allowed ones it will be rejected with this status code.\n\n","content":{"application/vnd.api+json":{"schema":{"type":"object","title":"Method not allowed","additionalProperties":false,"properties":{"errors":{"type":"array","minItems":1,"maxItems":1,"uniqueItems":true,"items":{"type":"object","additionalProperties":false,"properties":{"id":{"type":"string","title":"Type_ErrorIdentifier","description":"A system generated unique identifier for this request.","example":"rrt-1931948104716186917-c-geu2-10664-3111479-3.0"},"code":{"title":"Enum_Error_Method_Not_Allowed","type":"string","enum":["CM_NOT_ALLOWED"],"example":"CM_NOT_ALLOWED"},"links":{"type":"object","additionalProperties":false,"properties":{"about":{"type":"string","format":"uri","example":"https://digital.nhs.uk/developer/api-catalogue/nhs-notify","description":"https://digital.nhs.uk/developer/api-catalogue/nhs-notify"}},"minProperties":1},"status":{"type":"string","enum":["405"],"example":"405"},"title":{"type":"string","enum":["Method not allowed"],"example":"Method not allowed"},"detail":{"type":"string","enum":["The method at the requested URI was not allowed."],"example":"The method at the requested URI was not allowed."}}}}}}},"application/json":{"schema":{"type":"object","title":"Method not allowed","additionalProperties":false,"properties":{"errors":{"type":"array","minItems":1,"maxItems":1,"uniqueItems":true,"items":{"type":"object","additionalProperties":false,"properties":{"id":{"type":"string","title":"Type_ErrorIdentifier","description":"A system generated unique identifier for this request.","example":"rrt-1931948104716186917-c-geu2-10664-3111479-3.0"},"code":{"title":"Enum_Error_Method_Not_Allowed","type":"string","enum":["CM_NOT_ALLOWED"],"example":"CM_NOT_ALLOWED"},"links":{"type":"object","additionalProperties":false,"properties":{"about":{"type":"string","format":"uri","example":"https://digital.nhs.uk/developer/api-catalogue/nhs-notify","description":"https://digital.nhs.uk/developer/api-catalogue/nhs-notify"}},"minProperties":1},"status":{"type":"string","enum":["405"],"example":"405"},"title":{"type":"string","enum":["Method not allowed"],"example":"Method not allowed"},"detail":{"type":"string","enum":["The method at the requested URI was not allowed."],"example":"The method at the requested URI was not allowed."}}}}}}}},"headers":{"X-Correlation-ID":{"schema":{"type":"string","pattern":"11C46F5F-CDEF-4865-94B2-0EE0EDCC26DA","description":"If the X-Correlation-ID header was included in the request the value of this header will be equal to that. Otherwise it will be a unique alphanumeric string generated by NHS Notify."}}}},"406":{"description":"The request did not contain a valid `Accept` header value.\n\nValid values are:\n\n* `*/*`\n* `application/json`\n* `application/vnd.api+json`\n* `application/json; charset=utf-8`\n* `application/vnd.api+json; charset=utf-8`\n\nWhere no `Accept` header is present, this will default to `application/vnd.api+json`\n","content":{"application/vnd.api+json":{"schema":{"type":"object","title":"Not Acceptable","additionalProperties":false,"properties":{"errors":{"type":"array","minItems":1,"maxItems":1,"uniqueItems":true,"items":{"type":"object","additionalProperties":false,"properties":{"id":{"type":"string","title":"Type_ErrorIdentifier","description":"A system generated unique identifier for this request.","example":"rrt-1931948104716186917-c-geu2-10664-3111479-3.0"},"code":{"title":"Enum_Error_NotAcceptable","type":"string","enum":["CM_NOT_ACCEPTABLE"],"example":"CM_NOT_ACCEPTABLE"},"links":{"type":"object","additionalProperties":false,"properties":{"about":{"type":"string","format":"uri","example":"https://digital.nhs.uk/developer/api-catalogue/nhs-notify","description":"https://digital.nhs.uk/developer/api-catalogue/nhs-notify"}},"minProperties":1},"status":{"type":"string","enum":["406"],"example":"406"},"title":{"type":"string","enum":["Not acceptable"],"example":"Not acceptable"},"detail":{"type":"string","enum":["This service can only generate application/vnd.api+json or application/json."],"example":"This service can only generate application/vnd.api+json or application/json."},"source":{"type":"object","additionalProperties":false,"properties":{"header":{"type":"string","enum":["Accept"],"example":"Accept"}}}}}}}}}},"headers":{"X-Correlation-ID":{"schema":{"type":"string","pattern":"11C46F5F-CDEF-4865-94B2-0EE0EDCC26DA","description":"If the X-Correlation-ID header was included in the request the value of this header will be equal to that. Otherwise it will be a unique alphanumeric string generated by NHS Notify."}}}},"408":{"description":"There has been a client side issue reading your request. This can occur when there are networking issues between your application and our service.\n\nThere may also be an issue within our backend where a `408` has been bubbled up and exposed.\n\nThis could be indicative of an ongoing infrastructure issue that is out of our (or your) control.\n\n### Sandbox\n\nIt is possible to simulate this error response by sending a request with a header of `Prefer` set to the value `code=408`.\n\nHere is an example curl request to simulate this response:\n\n```\n curl -X GET --header \"Prefer: code=408\" https://sandbox.api.service.nhs.uk/comms/\n```\n\n","content":{"application/vnd.api+json":{"schema":{"type":"object","title":"Request timeout","additionalProperties":false,"properties":{"errors":{"type":"array","minItems":1,"maxItems":1,"uniqueItems":true,"items":{"type":"object","additionalProperties":false,"properties":{"id":{"type":"string","title":"Type_ErrorIdentifier","description":"A system generated unique identifier for this request.","example":"rrt-1931948104716186917-c-geu2-10664-3111479-3.0"},"code":{"title":"Enum_Error_Timeout","type":"string","enum":["CM_TIMEOUT"],"example":"CM_TIMEOUT"},"links":{"type":"object","additionalProperties":false,"properties":{"about":{"type":"string","format":"uri","example":"https://digital.nhs.uk/developer/api-catalogue/nhs-notify","description":"https://digital.nhs.uk/developer/api-catalogue/nhs-notify"}},"minProperties":1},"status":{"type":"string","enum":["408"],"example":"408"},"title":{"type":"string","enum":["Request timeout"],"example":"Request timeout"},"detail":{"type":"string","enum":["The service was unable to receive your request within the timeout period."],"example":"The service was unable to receive your request within the timeout period."}}}}}}},"application/json":{"schema":{"type":"object","title":"Request timeout","additionalProperties":false,"properties":{"errors":{"type":"array","minItems":1,"maxItems":1,"uniqueItems":true,"items":{"type":"object","additionalProperties":false,"properties":{"id":{"type":"string","title":"Type_ErrorIdentifier","description":"A system generated unique identifier for this request.","example":"rrt-1931948104716186917-c-geu2-10664-3111479-3.0"},"code":{"title":"Enum_Error_Timeout","type":"string","enum":["CM_TIMEOUT"],"example":"CM_TIMEOUT"},"links":{"type":"object","additionalProperties":false,"properties":{"about":{"type":"string","format":"uri","example":"https://digital.nhs.uk/developer/api-catalogue/nhs-notify","description":"https://digital.nhs.uk/developer/api-catalogue/nhs-notify"}},"minProperties":1},"status":{"type":"string","enum":["408"],"example":"408"},"title":{"type":"string","enum":["Request timeout"],"example":"Request timeout"},"detail":{"type":"string","enum":["The service was unable to receive your request within the timeout period."],"example":"The service was unable to receive your request within the timeout period."}}}}}}}},"headers":{"X-Correlation-ID":{"schema":{"type":"string","pattern":"11C46F5F-CDEF-4865-94B2-0EE0EDCC26DA","description":"If the X-Correlation-ID header was included in the request the value of this header will be equal to that. Otherwise it will be a unique alphanumeric string generated by NHS Notify."}}}},"415":{"description":"The `Content-Type` of the request is not supported. This endpoint supports:\n\n* `application/json`\n* `application/vnd.api+json`\n* `application/json; charset=utf-8`\n* `application/vnd.api+json; charset=utf-8`\n","content":{"application/vnd.api+json":{"schema":{"type":"object","title":"Unsupported Media","additionalProperties":false,"properties":{"errors":{"type":"array","minItems":1,"maxItems":1,"uniqueItems":true,"items":{"type":"object","additionalProperties":false,"properties":{"id":{"type":"string","title":"Type_ErrorIdentifier","description":"A system generated unique identifier for this request.","example":"rrt-1931948104716186917-c-geu2-10664-3111479-3.0"},"code":{"title":"Enum_Error_UnsupportedMedia","type":"string","enum":["CM_UNSUPPORTED_MEDIA"],"example":"CM_UNSUPPORTED_MEDIA"},"links":{"type":"object","additionalProperties":false,"properties":{"about":{"type":"string","format":"uri","example":"https://digital.nhs.uk/developer/api-catalogue/nhs-notify","description":"https://digital.nhs.uk/developer/api-catalogue/nhs-notify"}},"minProperties":1},"status":{"type":"string","enum":["415"],"example":"415"},"title":{"type":"string","enum":["Unsupported media"],"example":"Unsupported media"},"detail":{"type":"string","enum":["Invalid content-type, this API only supports application/vnd.api+json or application/json."],"example":"Invalid content-type, this API only supports application/vnd.api+json or application/json."},"source":{"type":"object","additionalProperties":false,"properties":{"header":{"type":"string","enum":["Content-Type"],"example":"Content-Type"}}}}}}}}},"application/json":{"schema":{"type":"object","title":"Unsupported Media","additionalProperties":false,"properties":{"errors":{"type":"array","minItems":1,"maxItems":1,"uniqueItems":true,"items":{"type":"object","additionalProperties":false,"properties":{"id":{"type":"string","title":"Type_ErrorIdentifier","description":"A system generated unique identifier for this request.","example":"rrt-1931948104716186917-c-geu2-10664-3111479-3.0"},"code":{"title":"Enum_Error_UnsupportedMedia","type":"string","enum":["CM_UNSUPPORTED_MEDIA"],"example":"CM_UNSUPPORTED_MEDIA"},"links":{"type":"object","additionalProperties":false,"properties":{"about":{"type":"string","format":"uri","example":"https://digital.nhs.uk/developer/api-catalogue/nhs-notify","description":"https://digital.nhs.uk/developer/api-catalogue/nhs-notify"}},"minProperties":1},"status":{"type":"string","enum":["415"],"example":"415"},"title":{"type":"string","enum":["Unsupported media"],"example":"Unsupported media"},"detail":{"type":"string","enum":["Invalid content-type, this API only supports application/vnd.api+json or application/json."],"example":"Invalid content-type, this API only supports application/vnd.api+json or application/json."},"source":{"type":"object","additionalProperties":false,"properties":{"header":{"type":"string","enum":["Content-Type"],"example":"Content-Type"}}}}}}}}}},"headers":{"X-Correlation-ID":{"schema":{"type":"string","pattern":"11C46F5F-CDEF-4865-94B2-0EE0EDCC26DA","description":"If the X-Correlation-ID header was included in the request the value of this header will be equal to that. Otherwise it will be a unique alphanumeric string generated by NHS Notify."}}}},"422":{"description":"Request already received and it will be ignored. Note that NHS Notify retains details of your original request for up to 9 months. Duplicate submissions received after this period will still be accepted.\n### Sandbox\n\nIt is possible to trigger this on the sandbox by using the `Prefer` header with a value of `code=422_message`.\n\nHere is an example curl request to trigger a `422`:\n\n```\n curl -X GET --header \"Prefer: code=422_message\" https://sandbox.api.service.nhs.uk/comms/\n```\n","content":{"application/vnd.api+json":{"schema":{"type":"object","title":"Duplicate Request","additionalProperties":false,"properties":{"errors":{"type":"array","minItems":1,"maxItems":1,"uniqueItems":true,"items":{"type":"object","additionalProperties":false,"properties":{"id":{"type":"string","title":"Type_ErrorIdentifier","description":"A system generated unique identifier for this request.","example":"rrt-1931948104716186917-c-geu2-10664-3111479-3.0"},"code":{"title":"Enum_Error_DuplicateRequest","type":"string","enum":["CM_DUPLICATE_REQUEST"],"example":"CM_DUPLICATE_REQUEST"},"links":{"type":"object","additionalProperties":false,"properties":{"about":{"type":"string","format":"uri","example":"https://digital.nhs.uk/developer/api-catalogue/nhs-notify","description":"https://digital.nhs.uk/developer/api-catalogue/nhs-notify"}},"minProperties":1},"status":{"type":"string","enum":["422"],"example":"422"},"title":{"type":"string","example":"Duplicate message request"},"detail":{"type":"string","example":"Request exists with identical messageReference"},"source":{"type":"object","additionalProperties":false,"properties":{"pointer":{"type":"string","example":"/data/attributes/messageReference"}}}}}}}}},"application/json":{"schema":{"type":"object","title":"Duplicate Request","additionalProperties":false,"properties":{"errors":{"type":"array","minItems":1,"maxItems":1,"uniqueItems":true,"items":{"type":"object","additionalProperties":false,"properties":{"id":{"type":"string","title":"Type_ErrorIdentifier","description":"A system generated unique identifier for this request.","example":"rrt-1931948104716186917-c-geu2-10664-3111479-3.0"},"code":{"title":"Enum_Error_DuplicateRequest","type":"string","enum":["CM_DUPLICATE_REQUEST"],"example":"CM_DUPLICATE_REQUEST"},"links":{"type":"object","additionalProperties":false,"properties":{"about":{"type":"string","format":"uri","example":"https://digital.nhs.uk/developer/api-catalogue/nhs-notify","description":"https://digital.nhs.uk/developer/api-catalogue/nhs-notify"}},"minProperties":1},"status":{"type":"string","enum":["422"],"example":"422"},"title":{"type":"string","example":"Duplicate message request"},"detail":{"type":"string","example":"Request exists with identical messageReference"},"source":{"type":"object","additionalProperties":false,"properties":{"pointer":{"type":"string","example":"/data/attributes/messageReference"}}}}}}}}}},"headers":{"X-Correlation-ID":{"schema":{"type":"string","pattern":"11C46F5F-CDEF-4865-94B2-0EE0EDCC26DA","description":"If the X-Correlation-ID header was included in the request the value of this header will be equal to that. Otherwise it will be a unique alphanumeric string generated by NHS Notify."}}}},"425":{"description":"You have retried this request too early, the previous request is still being processed. Re-send the request after the time (in seconds) specified in the `Retry-After` header.\n\n### Sandbox\n\nIt is possible to trigger this on the sandbox by using the `Prefer` header with a value of `code=425`.\n\nHere is an example curl request to trigger a `425`:\n\n```\n curl -X GET --header \"Prefer: code=425\" https://sandbox.api.service.nhs.uk/comms/\n```\n","content":{"application/vnd.api+json":{"schema":{"type":"object","title":"Retry too early","additionalProperties":false,"properties":{"errors":{"type":"array","minItems":1,"maxItems":1,"uniqueItems":true,"items":{"type":"object","additionalProperties":false,"properties":{"id":{"type":"string","title":"Type_ErrorIdentifier","description":"A system generated unique identifier for this request.","example":"rrt-1931948104716186917-c-geu2-10664-3111479-3.0"},"code":{"title":"Enum_Error_Retry_Too_Early","type":"string","enum":["CM_RETRY_TOO_EARLY"],"example":"CM_RETRY_TOO_EARLY"},"links":{"type":"object","additionalProperties":false,"properties":{"about":{"type":"string","format":"uri","example":"https://digital.nhs.uk/developer/api-catalogue/nhs-notify","description":"https://digital.nhs.uk/developer/api-catalogue/nhs-notify"}},"minProperties":1},"status":{"type":"string","enum":["425"],"example":"425"},"title":{"type":"string","enum":["Retried too early"],"example":"Retried too early"},"detail":{"type":"string","enum":["You have retried this request too early, the previous request is still being processed. Re-send the request after the time (in seconds) specified `Retry-After` header."],"example":"You have retried this request too early, the previous request is still being processed. Re-send the request after the time (in seconds) specified `Retry-After` header."}}}}}}},"application/json":{"schema":{"type":"object","title":"Retry too early","additionalProperties":false,"properties":{"errors":{"type":"array","minItems":1,"maxItems":1,"uniqueItems":true,"items":{"type":"object","additionalProperties":false,"properties":{"id":{"type":"string","title":"Type_ErrorIdentifier","description":"A system generated unique identifier for this request.","example":"rrt-1931948104716186917-c-geu2-10664-3111479-3.0"},"code":{"title":"Enum_Error_Retry_Too_Early","type":"string","enum":["CM_RETRY_TOO_EARLY"],"example":"CM_RETRY_TOO_EARLY"},"links":{"type":"object","additionalProperties":false,"properties":{"about":{"type":"string","format":"uri","example":"https://digital.nhs.uk/developer/api-catalogue/nhs-notify","description":"https://digital.nhs.uk/developer/api-catalogue/nhs-notify"}},"minProperties":1},"status":{"type":"string","enum":["425"],"example":"425"},"title":{"type":"string","enum":["Retried too early"],"example":"Retried too early"},"detail":{"type":"string","enum":["You have retried this request too early, the previous request is still being processed. Re-send the request after the time (in seconds) specified `Retry-After` header."],"example":"You have retried this request too early, the previous request is still being processed. Re-send the request after the time (in seconds) specified `Retry-After` header."}}}}}}}},"headers":{"Retry-After":{"schema":{"type":"integer","format":"duration","minimum":300,"multipleOf":1,"example":300},"description":"Time to wait before retrying the request."},"X-Correlation-ID":{"schema":{"type":"string","pattern":"11C46F5F-CDEF-4865-94B2-0EE0EDCC26DA","description":"If the X-Correlation-ID header was included in the request the value of this header will be equal to that. Otherwise it will be a unique alphanumeric string generated by NHS Notify."}}}},"429":{"description":"You have made too many requests too quickly, you must send requests at a slower rate.\n\nIf you have a retry mechanism in your HTTP client you may want to look at implementing an [exponential backoff](https://en.wikipedia.org/wiki/Exponential_backoff) or you can use the `Retry-After` response header to determine when you should retry your request.\n\n### Sandbox\n\nIt is possible to trigger this on the sandbox by using the `Prefer` header with a value of `code=429`.\n\nHere is an example curl request to trigger a `429`:\n\n```\n curl -X GET --header \"Prefer: code=429\" https://sandbox.api.service.nhs.uk/comms/\n```\n","content":{"application/vnd.api+json":{"schema":{"type":"object","title":"Too many requests","additionalProperties":false,"properties":{"errors":{"type":"array","minItems":1,"maxItems":1,"uniqueItems":true,"items":{"type":"object","additionalProperties":false,"properties":{"id":{"type":"string","title":"Type_ErrorIdentifier","description":"A system generated unique identifier for this request.","example":"rrt-1931948104716186917-c-geu2-10664-3111479-3.0"},"code":{"title":"Enum_Error_Quota","type":"string","enum":["CM_QUOTA"],"example":"CM_QUOTA"},"links":{"type":"object","additionalProperties":false,"properties":{"about":{"type":"string","format":"uri","example":"https://digital.nhs.uk/developer/api-catalogue/nhs-notify","description":"https://digital.nhs.uk/developer/api-catalogue/nhs-notify"}},"minProperties":1},"status":{"type":"string","enum":["429"],"example":"429"},"title":{"type":"string","enum":["Too many requests"],"example":"Too many requests"},"detail":{"type":"string","enum":["You have made too many requests. Re-send the request after the time (in seconds) specified `Retry-After` header."],"example":"You have made too many requests. Re-send the request after the time (in seconds) specified `Retry-After` header."}}}}}}},"application/json":{"schema":{"type":"object","title":"Too many requests","additionalProperties":false,"properties":{"errors":{"type":"array","minItems":1,"maxItems":1,"uniqueItems":true,"items":{"type":"object","additionalProperties":false,"properties":{"id":{"type":"string","title":"Type_ErrorIdentifier","description":"A system generated unique identifier for this request.","example":"rrt-1931948104716186917-c-geu2-10664-3111479-3.0"},"code":{"title":"Enum_Error_Quota","type":"string","enum":["CM_QUOTA"],"example":"CM_QUOTA"},"links":{"type":"object","additionalProperties":false,"properties":{"about":{"type":"string","format":"uri","example":"https://digital.nhs.uk/developer/api-catalogue/nhs-notify","description":"https://digital.nhs.uk/developer/api-catalogue/nhs-notify"}},"minProperties":1},"status":{"type":"string","enum":["429"],"example":"429"},"title":{"type":"string","enum":["Too many requests"],"example":"Too many requests"},"detail":{"type":"string","enum":["You have made too many requests. Re-send the request after the time (in seconds) specified `Retry-After` header."],"example":"You have made too many requests. Re-send the request after the time (in seconds) specified `Retry-After` header."}}}}}}}},"headers":{"Retry-After":{"schema":{"type":"integer","format":"duration","minimum":5,"multipleOf":1,"example":5},"description":"Time to wait between requests in seconds"},"X-Correlation-ID":{"schema":{"type":"string","pattern":"11C46F5F-CDEF-4865-94B2-0EE0EDCC26DA","description":"If the X-Correlation-ID header was included in the request the value of this header will be equal to that. Otherwise it will be a unique alphanumeric string generated by NHS Notify."}}}},"500":{"description":"An error has occured that is stopping your request from being processed. These errors may be thrown while the system is still being configured for your use, or a misconfiguration has occurred.\n\nThe following errors can occur:\n\n| Error code | Title | Description |\n| ---------- | ----- | ----------- |\n| `CM_MISSING_ROUTING_PLAN_TEMPLATE` | Templates missing | The templates required to use the routing plan were not found. |\n| `CM_ROUTING_PLAN_DUPLICATE_TEMPLATES` | Duplicate templates | The routing plan specified contains duplicate templates. |\n| `CM_INTERNAL_SERVER_ERROR` | Error processing request | There was an internal error whilst processing this request. |\n\nWithin each error is a source object which details the location of the error within your request body.\n\nCertain errors may include an extra set of metadata to assist you with resolving the problem.\n\nThis is done using a pointer that uses the [JSON Pointer](https://datatracker.ietf.org/doc/html/rfc6901) as per the [JSON:API Error Specification](https://jsonapi.org/format/#errors).\n\n### Sandbox\n\nIt is possible to simulate these errors by sending requests with specific routing plan identifiers.\n\nTo trigger the `CM_MISSING_ROUTING_PLAN_TEMPLATE` error use routing plan id `c8857ccf-06ec-483f-9b3a-7fc732d9ad48` or `aeb16ab8-cb9c-4d23-92e9-87c78119175c`. Here is an example curl request to simulate the response:\n\n```\n curl -X POST \\\n --header \"Accept: */*\" \\\n --header \"Content-type: application/vnd.api+json\" \\\n -d '{\"data\": {\"type\": \"Message\",\"attributes\": {\"routingPlanId\": \"c8857ccf-06ec-483f-9b3a-7fc732d9ad48\",\"messageReference\": \"da0b1495-c7cb-468c-9d81-07dee089d728\",\"recipient\": {\"nhsNumber\": \"9990548609\"},\"originator\": {\"odsCode\":\"X123\"},\"personalisation\": {}}}}' \\\n https://sandbox.api.service.nhs.uk/comms/v1/messages\n```\n\nTo trigger the `CM_ROUTING_PLAN_DUPLICATE_TEMPLATES` error use routing plan id `a3a4e55d-7a21-45a6-9286-8eb595c872a8`. Here is an example curl request to simulate the response:\n\n```\n curl -X POST \\\n --header \"Accept: */*\" \\\n --header \"Content-type: application/vnd.api+json\" \\\n -d '{\"data\": {\"type\": \"Message\",\"attributes\": {\"routingPlanId\": \"a3a4e55d-7a21-45a6-9286-8eb595c872a8\",\"messageReference\": \"da0b1495-c7cb-468c-9d81-07dee089d728\",\"recipient\": {\"nhsNumber\": \"9990548609\"},\"originator\": {\"odsCode\":\"X123\"},\"personalisation\": {}}}}' \\\n https://sandbox.api.service.nhs.uk/comms/v1/messages\n```\n\nIt is possible to trigger the `CM_INTERNAL_SERVER_ERROR` on the sandbox by using the `Prefer` header with a value of `code=500`.\n\nHere is an example curl request to trigger a `500`:\n\n```\n curl -X GET --header \"Prefer: code=500\" https://sandbox.api.service.nhs.uk/comms/\n```\n","content":{"application/vnd.api+json":{"schema":{"type":"object","title":"Internal server error","additionalProperties":false,"properties":{"errors":{"type":"array","minItems":1,"uniqueItems":true,"items":{"type":"object","additionalProperties":false,"properties":{"id":{"type":"string","title":"Type_ErrorIdentifier","description":"A system generated unique identifier for this request.","example":"rrt-1931948104716186917-c-geu2-10664-3111479-3.0"},"code":{"title":"Enum_Error_CreateMessageInternalServerError","type":"string","enum":["CM_ROUTING_PLAN_DUPLICATE_TEMPLATES","CM_MISSING_ROUTING_PLAN_TEMPLATE","CM_INTERNAL_SERVER_ERROR"],"example":"CM_MISSING_ROUTING_PLAN_TEMPLATE"},"links":{"type":"object","additionalProperties":false,"properties":{"about":{"type":"string","format":"uri","example":"https://digital.nhs.uk/developer/api-catalogue/nhs-notify","description":"https://digital.nhs.uk/developer/api-catalogue/nhs-notify"}},"minProperties":1},"status":{"type":"string","enum":["500"],"example":"500"},"title":{"type":"string","enum":["Templates missing","Duplicate templates","Error processing request"],"example":"Templates missing"},"detail":{"type":"string","enum":["The templates required to use the routing plan were not found.","The routing plan specified contains duplicate templates.","There was an internal error whilst processing this request."],"example":"The templates required to use the routing plan were not found."},"source":{"type":"object","additionalProperties":false,"properties":{"pointer":{"type":"string","enum":["/data/attributes/routingPlanId"],"example":"/data/attributes/routingPlanId"}}}}}}}}},"application/json":{"schema":{"type":"object","title":"Internal server error","additionalProperties":false,"properties":{"errors":{"type":"array","minItems":1,"uniqueItems":true,"items":{"type":"object","additionalProperties":false,"properties":{"id":{"type":"string","title":"Type_ErrorIdentifier","description":"A system generated unique identifier for this request.","example":"rrt-1931948104716186917-c-geu2-10664-3111479-3.0"},"code":{"title":"Enum_Error_CreateMessageInternalServerError","type":"string","enum":["CM_ROUTING_PLAN_DUPLICATE_TEMPLATES","CM_MISSING_ROUTING_PLAN_TEMPLATE","CM_INTERNAL_SERVER_ERROR"],"example":"CM_MISSING_ROUTING_PLAN_TEMPLATE"},"links":{"type":"object","additionalProperties":false,"properties":{"about":{"type":"string","format":"uri","example":"https://digital.nhs.uk/developer/api-catalogue/nhs-notify","description":"https://digital.nhs.uk/developer/api-catalogue/nhs-notify"}},"minProperties":1},"status":{"type":"string","enum":["500"],"example":"500"},"title":{"type":"string","enum":["Templates missing","Duplicate templates","Error processing request"],"example":"Templates missing"},"detail":{"type":"string","enum":["The templates required to use the routing plan were not found.","The routing plan specified contains duplicate templates.","There was an internal error whilst processing this request."],"example":"The templates required to use the routing plan were not found."},"source":{"type":"object","additionalProperties":false,"properties":{"pointer":{"type":"string","enum":["/data/attributes/routingPlanId"],"example":"/data/attributes/routingPlanId"}}}}}}}}}},"headers":{"X-Correlation-ID":{"schema":{"type":"string","pattern":"11C46F5F-CDEF-4865-94B2-0EE0EDCC26DA","description":"If the X-Correlation-ID header was included in the request the value of this header will be equal to that. Otherwise it will be a unique alphanumeric string generated by NHS Notify."}}}},"503":{"description":"The service is currently not accepting requests,\n\nThis error can occur if any part of the system has gone offline.\n\n### Sandbox\n\nIt is possible to simulate this error response by sending a request with a header of `Prefer` set to the value `code=503`.\n\nHere is an example curl request to simulate this response:\n\n```\n curl -X GET --header \"Prefer: code=503\" https://sandbox.api.service.nhs.uk/comms/\n```\n","content":{"application/vnd.api+json":{"schema":{"type":"object","title":"Service unavailable","additionalProperties":false,"properties":{"errors":{"type":"array","minItems":1,"maxItems":1,"uniqueItems":true,"items":{"type":"object","additionalProperties":false,"properties":{"id":{"type":"string","title":"Type_ErrorIdentifier","description":"A system generated unique identifier for this request.","example":"rrt-1931948104716186917-c-geu2-10664-3111479-3.0"},"code":{"title":"Enum_Error_ServiceUnavailable","type":"string","enum":["CM_SERVICE_UNAVAILABLE"],"example":"CM_SERVICE_UNAVAILABLE"},"links":{"type":"object","additionalProperties":false,"properties":{"about":{"type":"string","format":"uri","example":"https://digital.nhs.uk/developer/api-catalogue/nhs-notify","description":"https://digital.nhs.uk/developer/api-catalogue/nhs-notify"}},"minProperties":1},"status":{"type":"string","enum":["503"],"example":"503"},"title":{"type":"string","enum":["The service is currently unavailable"],"example":"The service is currently unavailable"},"detail":{"type":"string","enum":["The service is currently not able to process this request, try again later."],"example":"The service is currently not able to process this request, try again later."}}}}}}},"application/json":{"schema":{"type":"object","title":"Service unavailable","additionalProperties":false,"properties":{"errors":{"type":"array","minItems":1,"maxItems":1,"uniqueItems":true,"items":{"type":"object","additionalProperties":false,"properties":{"id":{"type":"string","title":"Type_ErrorIdentifier","description":"A system generated unique identifier for this request.","example":"rrt-1931948104716186917-c-geu2-10664-3111479-3.0"},"code":{"title":"Enum_Error_ServiceUnavailable","type":"string","enum":["CM_SERVICE_UNAVAILABLE"],"example":"CM_SERVICE_UNAVAILABLE"},"links":{"type":"object","additionalProperties":false,"properties":{"about":{"type":"string","format":"uri","example":"https://digital.nhs.uk/developer/api-catalogue/nhs-notify","description":"https://digital.nhs.uk/developer/api-catalogue/nhs-notify"}},"minProperties":1},"status":{"type":"string","enum":["503"],"example":"503"},"title":{"type":"string","enum":["The service is currently unavailable"],"example":"The service is currently unavailable"},"detail":{"type":"string","enum":["The service is currently not able to process this request, try again later."],"example":"The service is currently not able to process this request, try again later."}}}}}}}},"headers":{"Retry-After":{"schema":{"type":"integer","minimum":5,"multipleOf":1,"example":5},"description":"Time to wait between requests in seconds."},"X-Correlation-ID":{"schema":{"type":"string","pattern":"11C46F5F-CDEF-4865-94B2-0EE0EDCC26DA","description":"If the X-Correlation-ID header was included in the request the value of this header will be equal to that. Otherwise it will be a unique alphanumeric string generated by NHS Notify."}}}},"504":{"description":"There is an issue communicating to our backend services. If this occurs it is a good idea to back off and retry the request at a later time - see the [Circuit Breaker pattern](https://microservices.io/patterns/reliability/circuit-breaker.html).\n\nThis error can occur if there is an issue with a dependent service and so may be bubbled up from a 3rd party HTTP call.\n\n### Sandbox\n\nIt is possible to simulate this error response by sending a request with a header of `Prefer` set to the value `code=504`.\n\nHere is an example curl request to simulate this response:\n\n```\n curl -X GET --header \"Prefer: code=504\" https://sandbox.api.service.nhs.uk/comms/\n```\n\nTo simulate a backend `504` exception bubbling upwards you can send this request:\n\n```\n curl -X GET https://sandbox.api.service.nhs.uk/comms/_timeout_504\n```\n","content":{"application/vnd.api+json":{"schema":{"type":"object","title":"Service timeout","additionalProperties":false,"properties":{"errors":{"type":"array","minItems":1,"maxItems":1,"uniqueItems":true,"items":{"type":"object","additionalProperties":false,"properties":{"id":{"type":"string","title":"Type_ErrorIdentifier","description":"A system generated unique identifier for this request.","example":"rrt-1931948104716186917-c-geu2-10664-3111479-3.0"},"code":{"title":"Enum_Error_Timeout","type":"string","enum":["CM_TIMEOUT"],"example":"CM_TIMEOUT"},"links":{"type":"object","additionalProperties":false,"properties":{"about":{"type":"string","format":"uri","example":"https://digital.nhs.uk/developer/api-catalogue/nhs-notify","description":"https://digital.nhs.uk/developer/api-catalogue/nhs-notify"}},"minProperties":1},"status":{"type":"string","enum":["504"],"example":"504"},"title":{"type":"string","enum":["Unable to call service"],"example":"Unable to call service"},"detail":{"type":"string","enum":["The downstream service has not responded within the configured timeout period."],"example":"The downstream service has not responded within the configured timeout period."}}}}}}},"application/json":{"schema":{"type":"object","title":"Service timeout","additionalProperties":false,"properties":{"errors":{"type":"array","minItems":1,"maxItems":1,"uniqueItems":true,"items":{"type":"object","additionalProperties":false,"properties":{"id":{"type":"string","title":"Type_ErrorIdentifier","description":"A system generated unique identifier for this request.","example":"rrt-1931948104716186917-c-geu2-10664-3111479-3.0"},"code":{"title":"Enum_Error_Timeout","type":"string","enum":["CM_TIMEOUT"],"example":"CM_TIMEOUT"},"links":{"type":"object","additionalProperties":false,"properties":{"about":{"type":"string","format":"uri","example":"https://digital.nhs.uk/developer/api-catalogue/nhs-notify","description":"https://digital.nhs.uk/developer/api-catalogue/nhs-notify"}},"minProperties":1},"status":{"type":"string","enum":["504"],"example":"504"},"title":{"type":"string","enum":["Unable to call service"],"example":"Unable to call service"},"detail":{"type":"string","enum":["The downstream service has not responded within the configured timeout period."],"example":"The downstream service has not responded within the configured timeout period."}}}}}}}},"headers":{"X-Correlation-ID":{"schema":{"type":"string","pattern":"11C46F5F-CDEF-4865-94B2-0EE0EDCC26DA","description":"If the X-Correlation-ID header was included in the request the value of this header will be equal to that. Otherwise it will be a unique alphanumeric string generated by NHS Notify."}}}}}}},"/v1/messages/{messageId}":{"parameters":[{"schema":{"type":"string","title":"Type_KSUID","description":"The unique identifier for the message.","pattern":"^[a-zA-Z0-9]{27}$","minLength":27,"maxLength":27,"example":"2WL3qFTEFM0qMY8xjRbt1LIKCzM"},"name":"messageId","in":"path","required":true,"description":"The unique identifier for the message."}],"get":{"summary":"Get the status of a message","description":"## Overview\n\nUse this endpoint to fetch the status of a single message sent by your account.\n\n### Channels\n\nThe [NHS Notify Service](https://digital.nhs.uk/services/nhs-notify) supports multiple channels for delivering a message.\n\nThese channels are:\n\n* sms\n* email\n* letter\n* NHS app\n\nThe channels used to send your message are configured within the routing plan. These routing plans are configured during your [onboarding process](#overview--onboarding).\n\nThe channels configured in your routing plan at the time of sending are returned as part of the message status response. The channels are returned in the order that sending will be attempted.\n\nKey values that are returned for each of these channels are:\n\n* `type` - the channel type\n* `channelStatus` - the status of that channel\n* `channelStatusDescription` - the channel status description\n* `channelFailureReasonCode` - the channel failed reason code\n* `supplierStatus` - the status provided by the supplier for this channel\n* `retryCount` - the number of times we have attempted delivery, only returned if sending is retried one or more times.\n* `timestamps` - timestamps of key events\n* `routingPlan` - the routing plan that was used to generate the channel\n\nEach channel can have one of the following statuses:\n\n* `created` - the channel has been created\n* `skipped` - the channel has been skipped\n* `sending` - the channel is in the process of sending the message\n* `delivered` - the channel has delivered the message\n* `failed` - the channel has failed to deliver the message\n\nIf your routing plan supports conditional overrides, then in certain situations the routing plan referenced by a channel may be different from the one you initially requested. If this occurs then the `routingPlan.type` field will be set to the value `override`, plus the `id` and `version` fields will reflect the override that was used.\n\nThe following CURL request example highlights this interaction and can be replicated using message id `2bBBpsiMl2rnQt99qm6JLZ6w1vq`:\n```\ncurl -X GET 'https://sandbox.api.service.nhs.uk/comms/v1/messages/2bBBpsiMl2rnQt99qm6JLZ6w1vq' \\\n --header 'Accept: application/vnd.api+json'\n```\n\n### 3rd Party Querying\n\nThis system queries 3rd party integrations during the sending process. If this occurs, the `metadata` field will be populated with information about the queries made, including:\n\n* `queriedAt` - the date and time that the query occurred at\n* `version` - a version of the document returned in the query, if supported by the 3rd party\n* `labels` - the channels that the response affected\n* `source` - the 3rd party system the query was made to\n\nThe 3rd party systems being queried are:\n\n* `pds` - [Personal Demographics Service](https://digital.nhs.uk/services/personal-demographics-service)\n\n### Personalisation & Contact details\n\nPersonalisation and contact details are not returned within the messages. This is to ensure that Personally Identifiable Information cannot be extracted from the system.\n\n### Sandbox\n\nWhen sending this request on sandbox you can use one of these 5 message references:\n\n* single message status of delivered - `2WL3qFTEFM0qMY8xjRbt1LIKCzM`\n* single message delivered using multiple channels - `2WL5eYSWGzCHlGmzNxuqVusPxDg`\n* single message status of sending - `2WL4GEeFVxXG9S57nRlefBwwKxp`\n* single message failed as patient has an exit code - `2WL4mvx6eBva8dcIK60VEGIfcgZ`\n* single message routing plan overriden - `2bBBpsiMl2rnQt99qm6JLZ6w1vq`\n\nHere's an example curl command using one of the above message references:\n\n```\ncurl -X GET 'https://sandbox.api.service.nhs.uk/comms/v1/messages/2WL3qFTEFM0qMY8xjRbt1LIKCzM' \\\n --header 'Accept: application/vnd.api+json'\n```\n","operationId":"get-message","parameters":[{"name":"Authorization","in":"header","description":"An [OAuth 2.0 bearer token](https://digital.nhs.uk/developer/guides-and-documentation/security-and-authorisation/application-restricted-restful-apis-signed-jwt-authentication).\nRequired in all environments except sandbox.","schema":{"type":"string","format":"^Bearer [[:ascii:]]+$","example":"Bearer g1112R_ccQ1Ebbb4gtHBP1aaaNM"}},{"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.","schema":{"type":"string","example":"11C46F5F-CDEF-4865-94B2-0EE0EDCC26DA"}}],"responses":{"200":{"description":"The message has been found and its details are contained within the response body.","headers":{"X-Correlation-ID":{"schema":{"type":"string","pattern":"11C46F5F-CDEF-4865-94B2-0EE0EDCC26DA","description":"If the X-Correlation-ID header was included in the request the value of this header will be equal to that. Otherwise it will be a unique alphanumeric string generated by NHS Notify."}}},"content":{"application/vnd.api+json":{"schema":{"title":"MessageResponse","type":"object","additionalProperties":false,"properties":{"data":{"type":"object","additionalProperties":false,"required":["type","id","attributes","links"],"properties":{"type":{"title":"Enum_Message","type":"string","enum":["Message"],"example":"Message"},"id":{"type":"string","title":"Type_KSUID","description":"The unique identifier for the message.","pattern":"^[a-zA-Z0-9]{27}$","minLength":27,"maxLength":27,"example":"2WL3qFTEFM0qMY8xjRbt1LIKCzM"},"attributes":{"type":"object","additionalProperties":false,"required":["messageReference","messageStatus","timestamps","routingPlan"],"properties":{"messageReference":{"type":"string","description":"Your unique message reference, provided within the payload to create this message.","example":"da0b1495-c7cb-468c-9d81-07dee089d728"},"messageStatus":{"description":"The current status of this message at the time this response was generated.\n\nFor more information please check our documentation on message & channel statuses above.","title":"Enum_MessageStatus","type":"string","enum":["created","pending_enrichment","enriched","sending","delivered","failed"],"example":"sending"},"messageStatusDescription":{"type":"string","description":"If there is extra information associated with the status of this message, it is provided here.","example":"Failed reason: Contact detail is missing"},"messageFailureReasonCode":{"type":"string","description":"If there is a failed reason code associated with this message, it is provided here.","example":"MFR_PDSV_0002"},"channels":{"type":"array","description":"This array contains the channels that attempts to send your message will use, ordered as they will be attempted.\n\nThis array will remain empty (or not present) in the response until your message has gone through enrichment.","minItems":0,"items":{"type":"object","additionalProperties":false,"required":["type","cascadeType","cascadeOrder","channelStatus","timestamps","routingPlan"],"properties":{"type":{"title":"Enum_ChannelType","description":"The communication type of this channel.","type":"string","enum":["nhsapp","email","sms","letter"],"example":"email"},"retryCount":{"type":"integer","description":"Contains the number of times that we have attempted to send this message to this channel. Only returned if sending is retried one or more times.","example":1},"cascadeType":{"title":"Enum_CascadeType","description":"The cascade type of this message. You can set up primary or secondary message cascades in your routing plan. [Learn more about routing plans and message cascades](https://notify.nhs.uk/using-nhs-notify/routing-plans).","type":"string","enum":["primary","secondary"],"example":"primary"},"cascadeOrder":{"type":"integer","description":"The order of the message in your message cascade. The value is 1-based.","example":1},"channelStatus":{"description":"The current status of this channel at the time this response was generated.\n\nFor more information please check our documentation on message & channel statuses above.","title":"Enum_ChannelStatus","type":"string","enum":["created","sending","delivered","failed","skipped"],"example":"delivered"},"channelStatusDescription":{"type":"string","description":"If there is extra information associated with the status of this channel, it is provided here.","example":"Failed reason: Contact detail is missing"},"channelFailureReasonCode":{"type":"string","description":"If there is a failed reason code associated with this channel, it is provided here.","example":"CFR_PDSV_0002"},"supplierStatus":{"description":"The current status of this message within the channel at the time this response was generated.\n\nFor more information please check our documentation on message & channel statuses above.","title":"Enum_SupplierStatus","type":"string","enum":["delivered","read","notification_attempted","unnotified","rejected","notified","received","permanent_failure","temporary_failure","technical_failure","accepted","cancelled","pending_virus_check","validation_failed","unknown"],"example":"delivered"},"timestamps":{"type":"object","additionalProperties":false,"required":["created"],"properties":{"created":{"type":"string","description":"The date and time that this channel was created at.","format":"date-time","example":"2023-11-17T14:27:51.413Z"},"delivered":{"type":"string","description":"The date and time that this channel was successfully delivered.","format":"date-time","example":"2023-11-17T14:27:51.413Z"},"failed":{"type":"string","description":"The date and time that this channel failed to be delivered.","format":"date-time","example":"2023-11-17T14:27:51.413Z"}}},"routingPlan":{"type":"object","additionalProperties":false,"description":"The routing plan that this channel was generated from.","required":["id","type"],"properties":{"id":{"type":"string","format":"uuid","description":"The identifier for the routing plan.","example":"b838b13c-f98c-4def-93f0-515d4e4f4ee1"},"version":{"type":"string","description":"This identifies the specific version of the routing plan.","example":"ztoe2qRAM8M8vS0bqajhyEBcvXacrGPp"},"type":{"description":"Identifies if this is the original routing plan that was requested, or if a conditional override has been used.","title":"Enum_RoutingPlanType","type":"string","enum":["original","override"],"example":"original"}}},"metadata":{"type":"array","minItems":0,"description":"This array includes a list of all metadata lookups done for this channel within the system.\n\nCurrently only PDS is used for lookups.","items":{"type":"object","additionalProperties":false,"required":["source","label"],"properties":{"id":{"type":"string","description":"The sourceâs identifier for the metadata.","example":"y5z6a7b8"},"source":{"type":"string","description":"The source of the metadata.","example":"pds"},"label":{"title":"Enum_ChannelMetadataLabel","description":"The label associated with the metadata for this channel at the time this response was generated.","type":"string","enum":["recipient_contact"],"example":"recipient_contact"}}}}}}},"timestamps":{"type":"object","additionalProperties":false,"required":["created"],"properties":{"created":{"type":"string","description":"The date and time that your message was created at.","format":"date-time","example":"2023-11-17T14:27:51.413Z"},"enriched":{"type":"string","description":"The date and time when we enriched the recipients details from the [Personal Demographics Service](https://digital.nhs.uk/services/personal-demographics-service).\n\nThis is the business effective date that should be used when reviewing the patients details within PDS.","format":"date-time","example":"2023-11-17T14:27:51.413Z"},"delivered":{"type":"string","description":"The date and time that this message was successfully delivered.","format":"date-time","example":"2023-11-17T14:27:51.413Z"},"failed":{"type":"string","description":"The date and time that this message failed to be delivered.","format":"date-time","example":"2023-11-17T14:27:51.413Z"}}},"metadata":{"type":"array","minItems":0,"description":"This array includes a list of all metadata lookups done for this message within the system.\n\nCurrently only PDS is used for lookups.","items":{"type":"object","additionalProperties":false,"required":["queriedAt","source"],"properties":{"version":{"description":"This is the version of the document that was received from this source.","type":"string","example":2},"queriedAt":{"description":"This is the date and time the query was made (business effective date).","type":"string","format":"date-time","example":"2023-11-17T14:27:51.413Z"},"labels":{"description":"This is an array of labels indicating what this lookup affects. This may include the channels that were affected.","type":"array","items":{"title":"Enum_MetadataLabels","type":"string","enum":["nhsapp","email","sms","letter"],"example":"email"}},"source":{"description":"This is the service that was queried.","title":"Enum_MetadataSources","type":"string","enum":["pds"],"example":"pds"}}}},"routingPlan":{"description":"The routing plan that you requested the message be sent with.","type":"object","additionalProperties":false,"required":["id","name","createdDate"],"properties":{"id":{"type":"string","format":"uuid","description":"The identifier for the routing plan.","example":"b838b13c-f98c-4def-93f0-515d4e4f4ee1"},"name":{"type":"string","description":"The name of the routing plan.","example":"Plan Abc"},"version":{"type":"string","description":"This identifies the specific version of the routing plan.","example":"ztoe2qRAM8M8vS0bqajhyEBcvXacrGPp"},"createdDate":{"type":"string","description":"The creation date of the routing plan.","format":"date-time","example":"2023-11-17T14:27:51.413Z"}}}}},"relationships":{"type":"object","additionalProperties":false,"description":"This object contains information about other objects related to this message.","properties":{"messageBatch":{"type":"object","description":"If your message was sent as part of a batch, then this property will be present.","additionalProperties":false,"properties":{"data":{"type":"object","additionalProperties":false,"required":["type","id"],"properties":{"type":{"title":"Enum_MessageBatch","type":"string","enum":["MessageBatch"],"example":"MessageBatch"},"id":{"description":"This is the unique identifier of the batch that contains this message.","example":"2ZljUiS8NjJNs95PqiYOO7gAfJb","type":"string","title":"Type_KSUID","pattern":"^[a-zA-Z0-9]{27}$","minLength":27,"maxLength":27}}}}}}},"links":{"type":"object","additionalProperties":false,"description":"Contains links to related objects.","required":["self"],"properties":{"self":{"type":"string","format":"uri","description":"URI of this message.","example":"https://api.service.nhs.uk/comms/v1/messages/2WL3qFTEFM0qMY8xjRbt1LIKCzM"}}}}}}}},"application/json":{"schema":{"title":"MessageResponse","type":"object","additionalProperties":false,"properties":{"data":{"type":"object","additionalProperties":false,"required":["type","id","attributes","links"],"properties":{"type":{"title":"Enum_Message","type":"string","enum":["Message"],"example":"Message"},"id":{"type":"string","title":"Type_KSUID","description":"The unique identifier for the message.","pattern":"^[a-zA-Z0-9]{27}$","minLength":27,"maxLength":27,"example":"2WL3qFTEFM0qMY8xjRbt1LIKCzM"},"attributes":{"type":"object","additionalProperties":false,"required":["messageReference","messageStatus","timestamps","routingPlan"],"properties":{"messageReference":{"type":"string","description":"Your unique message reference, provided within the payload to create this message.","example":"da0b1495-c7cb-468c-9d81-07dee089d728"},"messageStatus":{"description":"The current status of this message at the time this response was generated.\n\nFor more information please check our documentation on message & channel statuses above.","title":"Enum_MessageStatus","type":"string","enum":["created","pending_enrichment","enriched","sending","delivered","failed"],"example":"sending"},"messageStatusDescription":{"type":"string","description":"If there is extra information associated with the status of this message, it is provided here.","example":"Failed reason: Contact detail is missing"},"messageFailureReasonCode":{"type":"string","description":"If there is a failed reason code associated with this message, it is provided here.","example":"MFR_PDSV_0002"},"channels":{"type":"array","description":"This array contains the channels that attempts to send your message will use, ordered as they will be attempted.\n\nThis array will remain empty (or not present) in the response until your message has gone through enrichment.","minItems":0,"items":{"type":"object","additionalProperties":false,"required":["type","cascadeType","cascadeOrder","channelStatus","timestamps","routingPlan"],"properties":{"type":{"title":"Enum_ChannelType","description":"The communication type of this channel.","type":"string","enum":["nhsapp","email","sms","letter"],"example":"email"},"retryCount":{"type":"integer","description":"Contains the number of times that we have attempted to send this message to this channel. Only returned if sending is retried one or more times.","example":1},"cascadeType":{"title":"Enum_CascadeType","description":"The cascade type of this message. You can set up primary or secondary message cascades in your routing plan. [Learn more about routing plans and message cascades](https://notify.nhs.uk/using-nhs-notify/routing-plans).","type":"string","enum":["primary","secondary"],"example":"primary"},"cascadeOrder":{"type":"integer","description":"The order of the message in your message cascade. The value is 1-based.","example":1},"channelStatus":{"description":"The current status of this channel at the time this response was generated.\n\nFor more information please check our documentation on message & channel statuses above.","title":"Enum_ChannelStatus","type":"string","enum":["created","sending","delivered","failed","skipped"],"example":"delivered"},"channelStatusDescription":{"type":"string","description":"If there is extra information associated with the status of this channel, it is provided here.","example":"Failed reason: Contact detail is missing"},"channelFailureReasonCode":{"type":"string","description":"If there is a failed reason code associated with this channel, it is provided here.","example":"CFR_PDSV_0002"},"supplierStatus":{"description":"The current status of this message within the channel at the time this response was generated.\n\nFor more information please check our documentation on message & channel statuses above.","title":"Enum_SupplierStatus","type":"string","enum":["delivered","read","notification_attempted","unnotified","rejected","notified","received","permanent_failure","temporary_failure","technical_failure","accepted","cancelled","pending_virus_check","validation_failed","unknown"],"example":"delivered"},"timestamps":{"type":"object","additionalProperties":false,"required":["created"],"properties":{"created":{"type":"string","description":"The date and time that this channel was created at.","format":"date-time","example":"2023-11-17T14:27:51.413Z"},"delivered":{"type":"string","description":"The date and time that this channel was successfully delivered.","format":"date-time","example":"2023-11-17T14:27:51.413Z"},"failed":{"type":"string","description":"The date and time that this channel failed to be delivered.","format":"date-time","example":"2023-11-17T14:27:51.413Z"}}},"routingPlan":{"type":"object","additionalProperties":false,"description":"The routing plan that this channel was generated from.","required":["id","type"],"properties":{"id":{"type":"string","format":"uuid","description":"The identifier for the routing plan.","example":"b838b13c-f98c-4def-93f0-515d4e4f4ee1"},"version":{"type":"string","description":"This identifies the specific version of the routing plan.","example":"ztoe2qRAM8M8vS0bqajhyEBcvXacrGPp"},"type":{"description":"Identifies if this is the original routing plan that was requested, or if a conditional override has been used.","title":"Enum_RoutingPlanType","type":"string","enum":["original","override"],"example":"original"}}},"metadata":{"type":"array","minItems":0,"description":"This array includes a list of all metadata lookups done for this channel within the system.\n\nCurrently only PDS is used for lookups.","items":{"type":"object","additionalProperties":false,"required":["source","label"],"properties":{"id":{"type":"string","description":"The sourceâs identifier for the metadata.","example":"y5z6a7b8"},"source":{"type":"string","description":"The source of the metadata.","example":"pds"},"label":{"title":"Enum_ChannelMetadataLabel","description":"The label associated with the metadata for this channel at the time this response was generated.","type":"string","enum":["recipient_contact"],"example":"recipient_contact"}}}}}}},"timestamps":{"type":"object","additionalProperties":false,"required":["created"],"properties":{"created":{"type":"string","description":"The date and time that your message was created at.","format":"date-time","example":"2023-11-17T14:27:51.413Z"},"enriched":{"type":"string","description":"The date and time when we enriched the recipients details from the [Personal Demographics Service](https://digital.nhs.uk/services/personal-demographics-service).\n\nThis is the business effective date that should be used when reviewing the patients details within PDS.","format":"date-time","example":"2023-11-17T14:27:51.413Z"},"delivered":{"type":"string","description":"The date and time that this message was successfully delivered.","format":"date-time","example":"2023-11-17T14:27:51.413Z"},"failed":{"type":"string","description":"The date and time that this message failed to be delivered.","format":"date-time","example":"2023-11-17T14:27:51.413Z"}}},"metadata":{"type":"array","minItems":0,"description":"This array includes a list of all metadata lookups done for this message within the system.\n\nCurrently only PDS is used for lookups.","items":{"type":"object","additionalProperties":false,"required":["queriedAt","source"],"properties":{"version":{"description":"This is the version of the document that was received from this source.","type":"string","example":2},"queriedAt":{"description":"This is the date and time the query was made (business effective date).","type":"string","format":"date-time","example":"2023-11-17T14:27:51.413Z"},"labels":{"description":"This is an array of labels indicating what this lookup affects. This may include the channels that were affected.","type":"array","items":{"title":"Enum_MetadataLabels","type":"string","enum":["nhsapp","email","sms","letter"],"example":"email"}},"source":{"description":"This is the service that was queried.","title":"Enum_MetadataSources","type":"string","enum":["pds"],"example":"pds"}}}},"routingPlan":{"description":"The routing plan that you requested the message be sent with.","type":"object","additionalProperties":false,"required":["id","name","createdDate"],"properties":{"id":{"type":"string","format":"uuid","description":"The identifier for the routing plan.","example":"b838b13c-f98c-4def-93f0-515d4e4f4ee1"},"name":{"type":"string","description":"The name of the routing plan.","example":"Plan Abc"},"version":{"type":"string","description":"This identifies the specific version of the routing plan.","example":"ztoe2qRAM8M8vS0bqajhyEBcvXacrGPp"},"createdDate":{"type":"string","description":"The creation date of the routing plan.","format":"date-time","example":"2023-11-17T14:27:51.413Z"}}}}},"relationships":{"type":"object","additionalProperties":false,"description":"This object contains information about other objects related to this message.","properties":{"messageBatch":{"type":"object","description":"If your message was sent as part of a batch, then this property will be present.","additionalProperties":false,"properties":{"data":{"type":"object","additionalProperties":false,"required":["type","id"],"properties":{"type":{"title":"Enum_MessageBatch","type":"string","enum":["MessageBatch"],"example":"MessageBatch"},"id":{"description":"This is the unique identifier of the batch that contains this message.","example":"2ZljUiS8NjJNs95PqiYOO7gAfJb","type":"string","title":"Type_KSUID","pattern":"^[a-zA-Z0-9]{27}$","minLength":27,"maxLength":27}}}}}}},"links":{"type":"object","additionalProperties":false,"description":"Contains links to related objects.","required":["self"],"properties":{"self":{"type":"string","format":"uri","description":"URI of this message.","example":"https://api.service.nhs.uk/comms/v1/messages/2WL3qFTEFM0qMY8xjRbt1LIKCzM"}}}}}}}}}},"401":{"description":"Your request was not authorized - you need to send a `Authorization` header with a valid `Bearer` token.\n\nSee the documentation on [how to generate a valid token](https://digital.nhs.uk/developer/guides-and-documentation/security-and-authorisation/application-restricted-restful-apis-signed-jwt-authentication).\n\n### Sandbox\n\nIt is possible to trigger this error in the sandbox by sending the header `Prefer` with a value of `code=401`.\n\nHere is an example curl request to trigger a `401`:\n\n```\n curl -X GET \\\n --header \"Accept: */*\" \\\n --header \"Prefer: code=401\" \\\n https://sandbox.api.service.nhs.uk/comms/\n```\n","content":{"application/vnd.api+json":{"schema":{"type":"object","title":"Access Denied","additionalProperties":false,"properties":{"errors":{"type":"array","minItems":1,"maxItems":1,"uniqueItems":true,"items":{"type":"object","additionalProperties":false,"properties":{"id":{"type":"string","title":"Type_ErrorIdentifier","description":"A system generated unique identifier for this request.","example":"rrt-1931948104716186917-c-geu2-10664-3111479-3.0"},"code":{"title":"Enum_Error_AccessDenied","type":"string","enum":["CM_DENIED"],"example":"CM_DENIED"},"links":{"type":"object","additionalProperties":false,"properties":{"about":{"type":"string","format":"uri","example":"https://digital.nhs.uk/developer/api-catalogue/nhs-notify","description":"https://digital.nhs.uk/developer/api-catalogue/nhs-notify"}},"minProperties":1},"status":{"type":"string","enum":["401"],"example":"401"},"title":{"type":"string","enum":["Access denied"],"example":"Access denied"},"detail":{"type":"string","enum":["Access token missing, invalid or expired, or calling application not configured for this operation."],"example":"Access token missing, invalid or expired, or calling application not configured for this operation."},"source":{"type":"object","additionalProperties":false,"properties":{"header":{"type":"string","enum":["Authorization"],"example":"Authorization"}}}}}}}}},"application/json":{"schema":{"type":"object","title":"Access Denied","additionalProperties":false,"properties":{"errors":{"type":"array","minItems":1,"maxItems":1,"uniqueItems":true,"items":{"type":"object","additionalProperties":false,"properties":{"id":{"type":"string","title":"Type_ErrorIdentifier","description":"A system generated unique identifier for this request.","example":"rrt-1931948104716186917-c-geu2-10664-3111479-3.0"},"code":{"title":"Enum_Error_AccessDenied","type":"string","enum":["CM_DENIED"],"example":"CM_DENIED"},"links":{"type":"object","additionalProperties":false,"properties":{"about":{"type":"string","format":"uri","example":"https://digital.nhs.uk/developer/api-catalogue/nhs-notify","description":"https://digital.nhs.uk/developer/api-catalogue/nhs-notify"}},"minProperties":1},"status":{"type":"string","enum":["401"],"example":"401"},"title":{"type":"string","enum":["Access denied"],"example":"Access denied"},"detail":{"type":"string","enum":["Access token missing, invalid or expired, or calling application not configured for this operation."],"example":"Access token missing, invalid or expired, or calling application not configured for this operation."},"source":{"type":"object","additionalProperties":false,"properties":{"header":{"type":"string","enum":["Authorization"],"example":"Authorization"}}}}}}}}}},"headers":{"X-Correlation-ID":{"schema":{"type":"string","pattern":"11C46F5F-CDEF-4865-94B2-0EE0EDCC26DA","description":"If the X-Correlation-ID header was included in the request the value of this header will be equal to that. Otherwise it will be a unique alphanumeric string generated by NHS Notify."}}}},"403":{"description":"Your request contained an authentic bearer token in the `Authorization` header but you are not authorized to make the request.\n\nIf the error code in the response is `CM_FORBIDDEN` then this could be due to the onboarding process not having been completed. Refer to our [onboarding](#overview--onboarding) section for more information.\n\nIf the response contains the error `CM_SERVICE_BAN` then there is a ban in effect on your account.\n\n### Sandbox\n\nIt is possible to trigger the `CM_FORBIDDEN` error in the sandbox by sending the header `Prefer` with a value of `code=403`.\n\nHere is an example curl request to trigger a `CM_FORBIDDEN`:\n\n```\n curl -X GET \\\n --header \"Accept: */*\" \\\n --header \"Prefer: code=403\" \\\n https://sandbox.api.service.nhs.uk/comms/\n```\n\nTo trigger the `CM_SERVICE_BAN` error in the sandbox by sending the header `Prefer` with a value of `code=403.1`.\n\nHere is an example curl request to trigger a `CM_SERVICE_BAN`:\n\n```\n curl -X GET \\\n --header \"Accept: */*\" \\\n --header \"Prefer: code=403.1\" \\\n https://sandbox.api.service.nhs.uk/comms/\n```\n","content":{"application/vnd.api+json":{"schema":{"type":"object","title":"Forbidden","additionalProperties":false,"properties":{"errors":{"type":"array","minItems":1,"maxItems":1,"uniqueItems":true,"items":{"type":"object","additionalProperties":false,"properties":{"id":{"type":"string","title":"Type_ErrorIdentifier","description":"A system generated unique identifier for this request.","example":"rrt-1931948104716186917-c-geu2-10664-3111479-3.0"},"code":{"title":"Enum_Error_Forbidden","type":"string","enum":["CM_FORBIDDEN","CM_SERVICE_BAN"],"example":"CM_FORBIDDEN"},"links":{"type":"object","additionalProperties":false,"properties":{"about":{"type":"string","format":"uri","example":"https://digital.nhs.uk/developer/api-catalogue/nhs-notify","description":"https://digital.nhs.uk/developer/api-catalogue/nhs-notify"}},"minProperties":1},"status":{"type":"string","enum":["403"],"example":"403"},"title":{"type":"string","enum":["Forbidden","Service ban in effect"],"example":"Forbidden"},"detail":{"type":"string","enum":["Client not recognised or not yet onboarded.","A service ban is in effect on your account."],"example":"Client not recognised or not yet onboarded."},"source":{"type":"object","additionalProperties":false,"properties":{"header":{"type":"string","enum":["Authorization"],"example":"Authorization"}}}}}}}}},"application/json":{"schema":{"type":"object","title":"Forbidden","additionalProperties":false,"properties":{"errors":{"type":"array","minItems":1,"maxItems":1,"uniqueItems":true,"items":{"type":"object","additionalProperties":false,"properties":{"id":{"type":"string","title":"Type_ErrorIdentifier","description":"A system generated unique identifier for this request.","example":"rrt-1931948104716186917-c-geu2-10664-3111479-3.0"},"code":{"title":"Enum_Error_Forbidden","type":"string","enum":["CM_FORBIDDEN","CM_SERVICE_BAN"],"example":"CM_FORBIDDEN"},"links":{"type":"object","additionalProperties":false,"properties":{"about":{"type":"string","format":"uri","example":"https://digital.nhs.uk/developer/api-catalogue/nhs-notify","description":"https://digital.nhs.uk/developer/api-catalogue/nhs-notify"}},"minProperties":1},"status":{"type":"string","enum":["403"],"example":"403"},"title":{"type":"string","enum":["Forbidden","Service ban in effect"],"example":"Forbidden"},"detail":{"type":"string","enum":["Client not recognised or not yet onboarded.","A service ban is in effect on your account."],"example":"Client not recognised or not yet onboarded."},"source":{"type":"object","additionalProperties":false,"properties":{"header":{"type":"string","enum":["Authorization"],"example":"Authorization"}}}}}}}}}},"headers":{"X-Correlation-ID":{"schema":{"type":"string","pattern":"11C46F5F-CDEF-4865-94B2-0EE0EDCC26DA","description":"If the X-Correlation-ID header was included in the request the value of this header will be equal to that. Otherwise it will be a unique alphanumeric string generated by NHS Notify."}}}},"404":{"description":"The message has not been found, check the message identifier passed in the URL for any errors and then try again.\n\n### Sandbox\n\nOn sandbox it is possible to simulate a 404 not found error using the `Prefer` header with a value of `code=404`.\n\nHere is an example curl request to trigger a `404`:\n\n```\n curl -X GET \\\n --header \"Accept: */*\" \\\n --header \"Content-type: application/vnd.api+json\" \\\n --header \"Prefer: code=404\" \\\n https://sandbox.api.service.nhs.uk/comms\n```\n","content":{"application/vnd.api+json":{"schema":{"type":"object","title":"Not found","additionalProperties":false,"properties":{"errors":{"type":"array","minItems":1,"maxItems":1,"uniqueItems":true,"items":{"type":"object","additionalProperties":false,"properties":{"id":{"type":"string","title":"Type_ErrorIdentifier","description":"A system generated unique identifier for this request.","example":"rrt-1931948104716186917-c-geu2-10664-3111479-3.0"},"code":{"title":"Enum_Error_NotFound","type":"string","enum":["CM_NOT_FOUND"],"example":"CM_NOT_FOUND"},"links":{"type":"object","additionalProperties":false,"properties":{"about":{"type":"string","format":"uri","example":"https://digital.nhs.uk/developer/api-catalogue/nhs-notify","description":"https://digital.nhs.uk/developer/api-catalogue/nhs-notify"}},"minProperties":1},"status":{"type":"string","enum":["404"],"example":"404"},"title":{"type":"string","enum":["Resource not found"],"example":"Resource not found"},"detail":{"type":"string","enum":["The resource at the requested URI was not found."],"example":"The resource at the requested URI was not found."}}}}}}},"application/json":{"schema":{"type":"object","title":"Not found","additionalProperties":false,"properties":{"errors":{"type":"array","minItems":1,"maxItems":1,"uniqueItems":true,"items":{"type":"object","additionalProperties":false,"properties":{"id":{"type":"string","title":"Type_ErrorIdentifier","description":"A system generated unique identifier for this request.","example":"rrt-1931948104716186917-c-geu2-10664-3111479-3.0"},"code":{"title":"Enum_Error_NotFound","type":"string","enum":["CM_NOT_FOUND"],"example":"CM_NOT_FOUND"},"links":{"type":"object","additionalProperties":false,"properties":{"about":{"type":"string","format":"uri","example":"https://digital.nhs.uk/developer/api-catalogue/nhs-notify","description":"https://digital.nhs.uk/developer/api-catalogue/nhs-notify"}},"minProperties":1},"status":{"type":"string","enum":["404"],"example":"404"},"title":{"type":"string","enum":["Resource not found"],"example":"Resource not found"},"detail":{"type":"string","enum":["The resource at the requested URI was not found."],"example":"The resource at the requested URI was not found."}}}}}}}},"headers":{"X-Correlation-ID":{"schema":{"type":"string","pattern":"11C46F5F-CDEF-4865-94B2-0EE0EDCC26DA","description":"If the X-Correlation-ID header was included in the request the value of this header will be equal to that. Otherwise it will be a unique alphanumeric string generated by NHS Notify."}}}},"405":{"description":"Your request specified a method that was not allowed on this endpoint.\n\nEndpoints only allow certain methods to be called on them. If your method was not one of the allowed ones it will be rejected with this status code.\n\n","content":{"application/vnd.api+json":{"schema":{"type":"object","title":"Method not allowed","additionalProperties":false,"properties":{"errors":{"type":"array","minItems":1,"maxItems":1,"uniqueItems":true,"items":{"type":"object","additionalProperties":false,"properties":{"id":{"type":"string","title":"Type_ErrorIdentifier","description":"A system generated unique identifier for this request.","example":"rrt-1931948104716186917-c-geu2-10664-3111479-3.0"},"code":{"title":"Enum_Error_Method_Not_Allowed","type":"string","enum":["CM_NOT_ALLOWED"],"example":"CM_NOT_ALLOWED"},"links":{"type":"object","additionalProperties":false,"properties":{"about":{"type":"string","format":"uri","example":"https://digital.nhs.uk/developer/api-catalogue/nhs-notify","description":"https://digital.nhs.uk/developer/api-catalogue/nhs-notify"}},"minProperties":1},"status":{"type":"string","enum":["405"],"example":"405"},"title":{"type":"string","enum":["Method not allowed"],"example":"Method not allowed"},"detail":{"type":"string","enum":["The method at the requested URI was not allowed."],"example":"The method at the requested URI was not allowed."}}}}}}},"application/json":{"schema":{"type":"object","title":"Method not allowed","additionalProperties":false,"properties":{"errors":{"type":"array","minItems":1,"maxItems":1,"uniqueItems":true,"items":{"type":"object","additionalProperties":false,"properties":{"id":{"type":"string","title":"Type_ErrorIdentifier","description":"A system generated unique identifier for this request.","example":"rrt-1931948104716186917-c-geu2-10664-3111479-3.0"},"code":{"title":"Enum_Error_Method_Not_Allowed","type":"string","enum":["CM_NOT_ALLOWED"],"example":"CM_NOT_ALLOWED"},"links":{"type":"object","additionalProperties":false,"properties":{"about":{"type":"string","format":"uri","example":"https://digital.nhs.uk/developer/api-catalogue/nhs-notify","description":"https://digital.nhs.uk/developer/api-catalogue/nhs-notify"}},"minProperties":1},"status":{"type":"string","enum":["405"],"example":"405"},"title":{"type":"string","enum":["Method not allowed"],"example":"Method not allowed"},"detail":{"type":"string","enum":["The method at the requested URI was not allowed."],"example":"The method at the requested URI was not allowed."}}}}}}}},"headers":{"X-Correlation-ID":{"schema":{"type":"string","pattern":"11C46F5F-CDEF-4865-94B2-0EE0EDCC26DA","description":"If the X-Correlation-ID header was included in the request the value of this header will be equal to that. Otherwise it will be a unique alphanumeric string generated by NHS Notify."}}}},"406":{"description":"The request did not contain a valid `Accept` header value.\n\nValid values are:\n\n* `*/*`\n* `application/json`\n* `application/vnd.api+json`\n* `application/json; charset=utf-8`\n* `application/vnd.api+json; charset=utf-8`\n\nWhere no `Accept` header is present, this will default to `application/vnd.api+json`\n","content":{"application/vnd.api+json":{"schema":{"type":"object","title":"Not Acceptable","additionalProperties":false,"properties":{"errors":{"type":"array","minItems":1,"maxItems":1,"uniqueItems":true,"items":{"type":"object","additionalProperties":false,"properties":{"id":{"type":"string","title":"Type_ErrorIdentifier","description":"A system generated unique identifier for this request.","example":"rrt-1931948104716186917-c-geu2-10664-3111479-3.0"},"code":{"title":"Enum_Error_NotAcceptable","type":"string","enum":["CM_NOT_ACCEPTABLE"],"example":"CM_NOT_ACCEPTABLE"},"links":{"type":"object","additionalProperties":false,"properties":{"about":{"type":"string","format":"uri","example":"https://digital.nhs.uk/developer/api-catalogue/nhs-notify","description":"https://digital.nhs.uk/developer/api-catalogue/nhs-notify"}},"minProperties":1},"status":{"type":"string","enum":["406"],"example":"406"},"title":{"type":"string","enum":["Not acceptable"],"example":"Not acceptable"},"detail":{"type":"string","enum":["This service can only generate application/vnd.api+json or application/json."],"example":"This service can only generate application/vnd.api+json or application/json."},"source":{"type":"object","additionalProperties":false,"properties":{"header":{"type":"string","enum":["Accept"],"example":"Accept"}}}}}}}}}},"headers":{"X-Correlation-ID":{"schema":{"type":"string","pattern":"11C46F5F-CDEF-4865-94B2-0EE0EDCC26DA","description":"If the X-Correlation-ID header was included in the request the value of this header will be equal to that. Otherwise it will be a unique alphanumeric string generated by NHS Notify."}}}},"408":{"description":"There has been a client side issue reading your request. This can occur when there are networking issues between your application and our service.\n\nThere may also be an issue within our backend where a `408` has been bubbled up and exposed.\n\nThis could be indicative of an ongoing infrastructure issue that is out of our (or your) control.\n\n### Sandbox\n\nIt is possible to simulate this error response by sending a request with a header of `Prefer` set to the value `code=408`.\n\nHere is an example curl request to simulate this response:\n\n```\n curl -X GET --header \"Prefer: code=408\" https://sandbox.api.service.nhs.uk/comms/\n```\n\n","content":{"application/vnd.api+json":{"schema":{"type":"object","title":"Request timeout","additionalProperties":false,"properties":{"errors":{"type":"array","minItems":1,"maxItems":1,"uniqueItems":true,"items":{"type":"object","additionalProperties":false,"properties":{"id":{"type":"string","title":"Type_ErrorIdentifier","description":"A system generated unique identifier for this request.","example":"rrt-1931948104716186917-c-geu2-10664-3111479-3.0"},"code":{"title":"Enum_Error_Timeout","type":"string","enum":["CM_TIMEOUT"],"example":"CM_TIMEOUT"},"links":{"type":"object","additionalProperties":false,"properties":{"about":{"type":"string","format":"uri","example":"https://digital.nhs.uk/developer/api-catalogue/nhs-notify","description":"https://digital.nhs.uk/developer/api-catalogue/nhs-notify"}},"minProperties":1},"status":{"type":"string","enum":["408"],"example":"408"},"title":{"type":"string","enum":["Request timeout"],"example":"Request timeout"},"detail":{"type":"string","enum":["The service was unable to receive your request within the timeout period."],"example":"The service was unable to receive your request within the timeout period."}}}}}}},"application/json":{"schema":{"type":"object","title":"Request timeout","additionalProperties":false,"properties":{"errors":{"type":"array","minItems":1,"maxItems":1,"uniqueItems":true,"items":{"type":"object","additionalProperties":false,"properties":{"id":{"type":"string","title":"Type_ErrorIdentifier","description":"A system generated unique identifier for this request.","example":"rrt-1931948104716186917-c-geu2-10664-3111479-3.0"},"code":{"title":"Enum_Error_Timeout","type":"string","enum":["CM_TIMEOUT"],"example":"CM_TIMEOUT"},"links":{"type":"object","additionalProperties":false,"properties":{"about":{"type":"string","format":"uri","example":"https://digital.nhs.uk/developer/api-catalogue/nhs-notify","description":"https://digital.nhs.uk/developer/api-catalogue/nhs-notify"}},"minProperties":1},"status":{"type":"string","enum":["408"],"example":"408"},"title":{"type":"string","enum":["Request timeout"],"example":"Request timeout"},"detail":{"type":"string","enum":["The service was unable to receive your request within the timeout period."],"example":"The service was unable to receive your request within the timeout period."}}}}}}}},"headers":{"X-Correlation-ID":{"schema":{"type":"string","pattern":"11C46F5F-CDEF-4865-94B2-0EE0EDCC26DA","description":"If the X-Correlation-ID header was included in the request the value of this header will be equal to that. Otherwise it will be a unique alphanumeric string generated by NHS Notify."}}}},"429":{"description":"You have made too many requests too quickly, you must send requests at a slower rate.\n\nIf you have a retry mechanism in your HTTP client you may want to look at implementing an [exponential backoff](https://en.wikipedia.org/wiki/Exponential_backoff) or you can use the `Retry-After` response header to determine when you should retry your request.\n\n### Sandbox\n\nIt is possible to trigger this on the sandbox by using the `Prefer` header with a value of `code=429`.\n\nHere is an example curl request to trigger a `429`:\n\n```\n curl -X GET --header \"Prefer: code=429\" https://sandbox.api.service.nhs.uk/comms/\n```\n","content":{"application/vnd.api+json":{"schema":{"type":"object","title":"Too many requests","additionalProperties":false,"properties":{"errors":{"type":"array","minItems":1,"maxItems":1,"uniqueItems":true,"items":{"type":"object","additionalProperties":false,"properties":{"id":{"type":"string","title":"Type_ErrorIdentifier","description":"A system generated unique identifier for this request.","example":"rrt-1931948104716186917-c-geu2-10664-3111479-3.0"},"code":{"title":"Enum_Error_Quota","type":"string","enum":["CM_QUOTA"],"example":"CM_QUOTA"},"links":{"type":"object","additionalProperties":false,"properties":{"about":{"type":"string","format":"uri","example":"https://digital.nhs.uk/developer/api-catalogue/nhs-notify","description":"https://digital.nhs.uk/developer/api-catalogue/nhs-notify"}},"minProperties":1},"status":{"type":"string","enum":["429"],"example":"429"},"title":{"type":"string","enum":["Too many requests"],"example":"Too many requests"},"detail":{"type":"string","enum":["You have made too many requests. Re-send the request after the time (in seconds) specified `Retry-After` header."],"example":"You have made too many requests. Re-send the request after the time (in seconds) specified `Retry-After` header."}}}}}}},"application/json":{"schema":{"type":"object","title":"Too many requests","additionalProperties":false,"properties":{"errors":{"type":"array","minItems":1,"maxItems":1,"uniqueItems":true,"items":{"type":"object","additionalProperties":false,"properties":{"id":{"type":"string","title":"Type_ErrorIdentifier","description":"A system generated unique identifier for this request.","example":"rrt-1931948104716186917-c-geu2-10664-3111479-3.0"},"code":{"title":"Enum_Error_Quota","type":"string","enum":["CM_QUOTA"],"example":"CM_QUOTA"},"links":{"type":"object","additionalProperties":false,"properties":{"about":{"type":"string","format":"uri","example":"https://digital.nhs.uk/developer/api-catalogue/nhs-notify","description":"https://digital.nhs.uk/developer/api-catalogue/nhs-notify"}},"minProperties":1},"status":{"type":"string","enum":["429"],"example":"429"},"title":{"type":"string","enum":["Too many requests"],"example":"Too many requests"},"detail":{"type":"string","enum":["You have made too many requests. Re-send the request after the time (in seconds) specified `Retry-After` header."],"example":"You have made too many requests. Re-send the request after the time (in seconds) specified `Retry-After` header."}}}}}}}},"headers":{"Retry-After":{"schema":{"type":"integer","format":"duration","minimum":5,"multipleOf":1,"example":5},"description":"Time to wait between requests in seconds"},"X-Correlation-ID":{"schema":{"type":"string","pattern":"11C46F5F-CDEF-4865-94B2-0EE0EDCC26DA","description":"If the X-Correlation-ID header was included in the request the value of this header will be equal to that. Otherwise it will be a unique alphanumeric string generated by NHS Notify."}}}},"500":{"description":"An error has occured that is stopping your request from being processed.\n\n### Sandbox\n\nIt is possible to trigger the `CM_INTERNAL_SERVER_ERROR` on the sandbox by using the `Prefer` header with a value of `code=500`.\n\nHere is an example curl request to trigger a `500`:\n\n```\n curl -X GET --header \"Prefer: code=500\" https://sandbox.api.service.nhs.uk/comms\n```\n","content":{"application/vnd.api+json":{"schema":{"type":"object","title":"Internal server error","additionalProperties":false,"properties":{"errors":{"type":"array","minItems":1,"uniqueItems":true,"items":{"type":"object","additionalProperties":false,"properties":{"id":{"type":"string","title":"Type_ErrorIdentifier","description":"A system generated unique identifier for this request.","example":"rrt-1931948104716186917-c-geu2-10664-3111479-3.0"},"code":{"title":"Enum_Error_InternalServerError","type":"string","enum":["CM_INTERNAL_SERVER_ERROR"],"example":"CM_INTERNAL_SERVER_ERROR"},"links":{"type":"object","additionalProperties":false,"properties":{"about":{"type":"string","format":"uri","example":"https://digital.nhs.uk/developer/api-catalogue/nhs-notify","description":"https://digital.nhs.uk/developer/api-catalogue/nhs-notify"}},"minProperties":1},"status":{"type":"string","enum":["500"],"example":"500"},"title":{"type":"string","enum":["Error processing request"],"example":"Error processing request"},"detail":{"type":"string","enum":["There was an internal error whilst processing this request."],"example":"There was an internal error whilst processing this request."}}}}}}},"application/json":{"schema":{"type":"object","title":"Internal server error","additionalProperties":false,"properties":{"errors":{"type":"array","minItems":1,"uniqueItems":true,"items":{"type":"object","additionalProperties":false,"properties":{"id":{"type":"string","title":"Type_ErrorIdentifier","description":"A system generated unique identifier for this request.","example":"rrt-1931948104716186917-c-geu2-10664-3111479-3.0"},"code":{"title":"Enum_Error_InternalServerError","type":"string","enum":["CM_INTERNAL_SERVER_ERROR"],"example":"CM_INTERNAL_SERVER_ERROR"},"links":{"type":"object","additionalProperties":false,"properties":{"about":{"type":"string","format":"uri","example":"https://digital.nhs.uk/developer/api-catalogue/nhs-notify","description":"https://digital.nhs.uk/developer/api-catalogue/nhs-notify"}},"minProperties":1},"status":{"type":"string","enum":["500"],"example":"500"},"title":{"type":"string","enum":["Error processing request"],"example":"Error processing request"},"detail":{"type":"string","enum":["There was an internal error whilst processing this request."],"example":"There was an internal error whilst processing this request."}}}}}}}},"headers":{"X-Correlation-ID":{"schema":{"type":"string","pattern":"11C46F5F-CDEF-4865-94B2-0EE0EDCC26DA","description":"If the X-Correlation-ID header was included in the request the value of this header will be equal to that. Otherwise it will be a unique alphanumeric string generated by NHS Notify."}}}},"503":{"description":"The service is currently not accepting requests,\n\nThis error can occur if any part of the system has gone offline.\n\n### Sandbox\n\nIt is possible to simulate this error response by sending a request with a header of `Prefer` set to the value `code=503`.\n\nHere is an example curl request to simulate this response:\n\n```\n curl -X GET --header \"Prefer: code=503\" https://sandbox.api.service.nhs.uk/comms/\n```\n","content":{"application/vnd.api+json":{"schema":{"type":"object","title":"Service unavailable","additionalProperties":false,"properties":{"errors":{"type":"array","minItems":1,"maxItems":1,"uniqueItems":true,"items":{"type":"object","additionalProperties":false,"properties":{"id":{"type":"string","title":"Type_ErrorIdentifier","description":"A system generated unique identifier for this request.","example":"rrt-1931948104716186917-c-geu2-10664-3111479-3.0"},"code":{"title":"Enum_Error_ServiceUnavailable","type":"string","enum":["CM_SERVICE_UNAVAILABLE"],"example":"CM_SERVICE_UNAVAILABLE"},"links":{"type":"object","additionalProperties":false,"properties":{"about":{"type":"string","format":"uri","example":"https://digital.nhs.uk/developer/api-catalogue/nhs-notify","description":"https://digital.nhs.uk/developer/api-catalogue/nhs-notify"}},"minProperties":1},"status":{"type":"string","enum":["503"],"example":"503"},"title":{"type":"string","enum":["The service is currently unavailable"],"example":"The service is currently unavailable"},"detail":{"type":"string","enum":["The service is currently not able to process this request, try again later."],"example":"The service is currently not able to process this request, try again later."}}}}}}},"application/json":{"schema":{"type":"object","title":"Service unavailable","additionalProperties":false,"properties":{"errors":{"type":"array","minItems":1,"maxItems":1,"uniqueItems":true,"items":{"type":"object","additionalProperties":false,"properties":{"id":{"type":"string","title":"Type_ErrorIdentifier","description":"A system generated unique identifier for this request.","example":"rrt-1931948104716186917-c-geu2-10664-3111479-3.0"},"code":{"title":"Enum_Error_ServiceUnavailable","type":"string","enum":["CM_SERVICE_UNAVAILABLE"],"example":"CM_SERVICE_UNAVAILABLE"},"links":{"type":"object","additionalProperties":false,"properties":{"about":{"type":"string","format":"uri","example":"https://digital.nhs.uk/developer/api-catalogue/nhs-notify","description":"https://digital.nhs.uk/developer/api-catalogue/nhs-notify"}},"minProperties":1},"status":{"type":"string","enum":["503"],"example":"503"},"title":{"type":"string","enum":["The service is currently unavailable"],"example":"The service is currently unavailable"},"detail":{"type":"string","enum":["The service is currently not able to process this request, try again later."],"example":"The service is currently not able to process this request, try again later."}}}}}}}},"headers":{"Retry-After":{"schema":{"type":"integer","minimum":5,"multipleOf":1,"example":5},"description":"Time to wait between requests in seconds."},"X-Correlation-ID":{"schema":{"type":"string","pattern":"11C46F5F-CDEF-4865-94B2-0EE0EDCC26DA","description":"If the X-Correlation-ID header was included in the request the value of this header will be equal to that. Otherwise it will be a unique alphanumeric string generated by NHS Notify."}}}},"504":{"description":"There is an issue communicating to our backend services. If this occurs it is a good idea to back off and retry the request at a later time - see the [Circuit Breaker pattern](https://microservices.io/patterns/reliability/circuit-breaker.html).\n\nThis error can occur if there is an issue with a dependent service and so may be bubbled up from a 3rd party HTTP call.\n\n### Sandbox\n\nIt is possible to simulate this error response by sending a request with a header of `Prefer` set to the value `code=504`.\n\nHere is an example curl request to simulate this response:\n\n```\n curl -X GET --header \"Prefer: code=504\" https://sandbox.api.service.nhs.uk/comms/\n```\n\nTo simulate a backend `504` exception bubbling upwards you can send this request:\n\n```\n curl -X GET https://sandbox.api.service.nhs.uk/comms/_timeout_504\n```\n","content":{"application/vnd.api+json":{"schema":{"type":"object","title":"Service timeout","additionalProperties":false,"properties":{"errors":{"type":"array","minItems":1,"maxItems":1,"uniqueItems":true,"items":{"type":"object","additionalProperties":false,"properties":{"id":{"type":"string","title":"Type_ErrorIdentifier","description":"A system generated unique identifier for this request.","example":"rrt-1931948104716186917-c-geu2-10664-3111479-3.0"},"code":{"title":"Enum_Error_Timeout","type":"string","enum":["CM_TIMEOUT"],"example":"CM_TIMEOUT"},"links":{"type":"object","additionalProperties":false,"properties":{"about":{"type":"string","format":"uri","example":"https://digital.nhs.uk/developer/api-catalogue/nhs-notify","description":"https://digital.nhs.uk/developer/api-catalogue/nhs-notify"}},"minProperties":1},"status":{"type":"string","enum":["504"],"example":"504"},"title":{"type":"string","enum":["Unable to call service"],"example":"Unable to call service"},"detail":{"type":"string","enum":["The downstream service has not responded within the configured timeout period."],"example":"The downstream service has not responded within the configured timeout period."}}}}}}},"application/json":{"schema":{"type":"object","title":"Service timeout","additionalProperties":false,"properties":{"errors":{"type":"array","minItems":1,"maxItems":1,"uniqueItems":true,"items":{"type":"object","additionalProperties":false,"properties":{"id":{"type":"string","title":"Type_ErrorIdentifier","description":"A system generated unique identifier for this request.","example":"rrt-1931948104716186917-c-geu2-10664-3111479-3.0"},"code":{"title":"Enum_Error_Timeout","type":"string","enum":["CM_TIMEOUT"],"example":"CM_TIMEOUT"},"links":{"type":"object","additionalProperties":false,"properties":{"about":{"type":"string","format":"uri","example":"https://digital.nhs.uk/developer/api-catalogue/nhs-notify","description":"https://digital.nhs.uk/developer/api-catalogue/nhs-notify"}},"minProperties":1},"status":{"type":"string","enum":["504"],"example":"504"},"title":{"type":"string","enum":["Unable to call service"],"example":"Unable to call service"},"detail":{"type":"string","enum":["The downstream service has not responded within the configured timeout period."],"example":"The downstream service has not responded within the configured timeout period."}}}}}}}},"headers":{"X-Correlation-ID":{"schema":{"type":"string","pattern":"11C46F5F-CDEF-4865-94B2-0EE0EDCC26DA","description":"If the X-Correlation-ID header was included in the request the value of this header will be equal to that. Otherwise it will be a unique alphanumeric string generated by NHS Notify."}}}}}}},"/channels/nhsapp/accounts":{"get":{"summary":"Get NHS App Account details","description":"## Overview\n\nUse this endpoint to get details of patients registered with the NHS App for a given GP surgery, and an indication of whether they have enabled push notifications on one or more devices. The response will only include patients who have had their identity verified to the high (P9) level.\n\nThis information can be used by client applications to determine whether it is appropriate to attempt to use the NHS App channel to send in-app messages and push notifications to patients, or if alternative communication channels should be used instead.\n\nThe information provided by this endpoint is generated by a daily batch process. Client applications should cache and refresh local copies of this data accordingly.\n\n## Pagination\n\nTo avoid returning excessively large response bodies, the results may be split across multiple pages. On retrieving the response for the first page of results, the Response body will contain links to the current page, the next page and the last page. If there are further pages, these can be retrieved by making additional request(s) with the page parameter specified.\n","operationId":"get-nhsapp-account-details","parameters":[{"name":"Authorization","in":"header","description":"An [OAuth 2.0 bearer token](https://digital.nhs.uk/developer/guides-and-documentation/security-and-authorisation/application-restricted-restful-apis-signed-jwt-authentication).\nRequired in all environments except sandbox.","schema":{"type":"string","format":"^Bearer [[:ascii:]]+$","example":"Bearer g1112R_ccQ1Ebbb4gtHBP1aaaNM"}},{"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.","schema":{"type":"string","example":"11C46F5F-CDEF-4865-94B2-0EE0EDCC26DA"}},{"name":"ods-organisation-code","in":"query","required":true,"description":"The Organisation Data Service (ODS) code of the GP practice for which to retrieve a list of NHS App users. Not case sensitive.","schema":{"type":"string","title":"Type_ODSOrganisationCode","example":"Y00001"}},{"name":"page","in":"query","description":"The ordinal number of the page of results to be retrieved. If omitted, the\nfirst page of results will be returned. Use the links section in the response\nbody to determine whether any further pages of results exist.","schema":{"type":"number","example":1}}],"responses":{"200":{"description":"Request successful.","headers":{"X-Correlation-ID":{"schema":{"type":"string","pattern":"11C46F5F-CDEF-4865-94B2-0EE0EDCC26DA","description":"If the X-Correlation-ID header was included in the request the value of this header will be equal to that. Otherwise it will be a unique alphanumeric string generated by NHS Notify."}}},"content":{"application/vnd.api+json":{"schema":{"title":"NHSAppAccountDetailsResponse","type":"object","additionalProperties":false,"properties":{"data":{"type":"object","additionalProperties":false,"required":["type","id","attributes"],"properties":{"type":{"title":"Type_NhsAppAccounts","type":"string","enum":["NhsAppAccounts"],"example":"NhsAppAccounts"},"id":{"description":"The ODS organisation code that was specified in the request.","type":"string","title":"Type_ODSOrganisationCode","example":"Y00001"},"attributes":{"type":"object","additionalProperties":false,"required":["accounts"],"properties":{"accounts":{"type":"array","items":{"type":"object","additionalProperties":false,"required":["nhsNumber","notificationsEnabled"],"properties":{"nhsNumber":{"description":"The patient's NHS number.","type":"string","title":"Type_NHSNumber","pattern":"^[0-9]{10}$","minLength":10,"maxLength":10,"example":9044151320},"notificationsEnabled":{"description":"Indicates whether the patient has enabled native Android or Apple push notifications on at least one device.","type":"boolean","example":true}}}}}}}},"links":{"type":"object","additionalProperties":false,"description":"Contains links to related objects.","required":["last","self"],"properties":{"last":{"type":"string","format":"uri","description":"URI of the final page of data.","example":"https://api.service.nhs.uk/comms/channels/nhsapp/accounts?ods-organisation-code=Y00001&page=10"},"next":{"type":"string","format":"uri","description":"URI of the next page of data.","example":"https://api.service.nhs.uk/comms/channels/nhsapp/accounts?ods-organisation-code=Y00001&page=7"},"self":{"type":"string","format":"uri","description":"URI of this page of data.","example":"https://api.service.nhs.uk/comms/channels/nhsapp/accounts?ods-organisation-code=Y00001&page=6"}}}}}},"application/json":{"schema":{"title":"NHSAppAccountDetailsResponse","type":"object","additionalProperties":false,"properties":{"data":{"type":"object","additionalProperties":false,"required":["type","id","attributes"],"properties":{"type":{"title":"Type_NhsAppAccounts","type":"string","enum":["NhsAppAccounts"],"example":"NhsAppAccounts"},"id":{"description":"The ODS organisation code that was specified in the request.","type":"string","title":"Type_ODSOrganisationCode","example":"Y00001"},"attributes":{"type":"object","additionalProperties":false,"required":["accounts"],"properties":{"accounts":{"type":"array","items":{"type":"object","additionalProperties":false,"required":["nhsNumber","notificationsEnabled"],"properties":{"nhsNumber":{"description":"The patient's NHS number.","type":"string","title":"Type_NHSNumber","pattern":"^[0-9]{10}$","minLength":10,"maxLength":10,"example":9044151320},"notificationsEnabled":{"description":"Indicates whether the patient has enabled native Android or Apple push notifications on at least one device.","type":"boolean","example":true}}}}}}}},"links":{"type":"object","additionalProperties":false,"description":"Contains links to related objects.","required":["last","self"],"properties":{"last":{"type":"string","format":"uri","description":"URI of the final page of data.","example":"https://api.service.nhs.uk/comms/channels/nhsapp/accounts?ods-organisation-code=Y00001&page=10"},"next":{"type":"string","format":"uri","description":"URI of the next page of data.","example":"https://api.service.nhs.uk/comms/channels/nhsapp/accounts?ods-organisation-code=Y00001&page=7"},"self":{"type":"string","format":"uri","description":"URI of this page of data.","example":"https://api.service.nhs.uk/comms/channels/nhsapp/accounts?ods-organisation-code=Y00001&page=6"}}}}}}}},"400":{"description":"A validation error has occurred with the request sent.\n\nThe following validation errors can occur:\n\n| Error code | Title | Description |\n| ---------- | ----- | ----------- |\n| `CM_INVALID_REQUEST` | Invalid Request | The ODS code is missing or invalid, detail provided in the `detail` field. |\n\nWithin each error is a source object which details the location of the error within your request body.\n\nThis is done using a pointer that uses the [JSON Pointer](https://datatracker.ietf.org/doc/html/rfc6901) as per the [JSON:API Error Specification](https://jsonapi.org/format/#errors).\n","content":{"application/vnd.api+json":{"schema":{"type":"object","title":"Request not processable","additionalProperties":false,"properties":{"errors":{"type":"array","minItems":1,"uniqueItems":true,"items":{"type":"object","additionalProperties":false,"properties":{"id":{"type":"string","title":"Type_ErrorIdentifier","description":"A system generated unique identifier for this request.","example":"rrt-1931948104716186917-c-geu2-10664-3111479-3.0"},"code":{"type":"string","enum":["CM_INVALID_REQUEST"],"example":"CM_INVALID_REQUEST","title":"Enum_Error_InvalidGetNHSAppAccounts_Request"},"links":{"type":"object","additionalProperties":false,"properties":{"about":{"type":"string","format":"uri","example":"https://digital.nhs.uk/developer/api-catalogue/nhs-notify","description":"https://digital.nhs.uk/developer/api-catalogue/nhs-notify"}},"minProperties":1},"status":{"type":"string","enum":["400"],"example":"400"},"title":{"type":"string","enum":["Invalid Request"],"example":"Invalid Request"},"detail":{"type":"string","enum":["Invalid ODS Code","Missing ODS Code"],"example":"Invalid ODS Code"}}}}}}},"application/json":{"schema":{"type":"object","title":"Request not processable","additionalProperties":false,"properties":{"errors":{"type":"array","minItems":1,"uniqueItems":true,"items":{"type":"object","additionalProperties":false,"properties":{"id":{"type":"string","title":"Type_ErrorIdentifier","description":"A system generated unique identifier for this request.","example":"rrt-1931948104716186917-c-geu2-10664-3111479-3.0"},"code":{"type":"string","enum":["CM_INVALID_REQUEST"],"example":"CM_INVALID_REQUEST","title":"Enum_Error_InvalidGetNHSAppAccounts_Request"},"links":{"type":"object","additionalProperties":false,"properties":{"about":{"type":"string","format":"uri","example":"https://digital.nhs.uk/developer/api-catalogue/nhs-notify","description":"https://digital.nhs.uk/developer/api-catalogue/nhs-notify"}},"minProperties":1},"status":{"type":"string","enum":["400"],"example":"400"},"title":{"type":"string","enum":["Invalid Request"],"example":"Invalid Request"},"detail":{"type":"string","enum":["Invalid ODS Code","Missing ODS Code"],"example":"Invalid ODS Code"}}}}}}}},"headers":{"X-Correlation-ID":{"schema":{"type":"string","pattern":"11C46F5F-CDEF-4865-94B2-0EE0EDCC26DA","description":"If the X-Correlation-ID header was included in the request the value of this header will be equal to that. Otherwise it will be a unique alphanumeric string generated by NHS Notify."}}}},"401":{"description":"Your request was not authorized - you need to send a `Authorization` header with a valid `Bearer` token.\n\nSee the documentation on [how to generate a valid token](https://digital.nhs.uk/developer/guides-and-documentation/security-and-authorisation/application-restricted-restful-apis-signed-jwt-authentication).\n\n### Sandbox\n\nIt is possible to trigger this error in the sandbox by sending the header `Prefer` with a value of `code=401`.\n\nHere is an example curl request to trigger a `401`:\n\n```\n curl -X GET \\\n --header \"Accept: */*\" \\\n --header \"Prefer: code=401\" \\\n https://sandbox.api.service.nhs.uk/comms/\n```\n","content":{"application/vnd.api+json":{"schema":{"type":"object","title":"Access Denied","additionalProperties":false,"properties":{"errors":{"type":"array","minItems":1,"maxItems":1,"uniqueItems":true,"items":{"type":"object","additionalProperties":false,"properties":{"id":{"type":"string","title":"Type_ErrorIdentifier","description":"A system generated unique identifier for this request.","example":"rrt-1931948104716186917-c-geu2-10664-3111479-3.0"},"code":{"title":"Enum_Error_AccessDenied","type":"string","enum":["CM_DENIED"],"example":"CM_DENIED"},"links":{"type":"object","additionalProperties":false,"properties":{"about":{"type":"string","format":"uri","example":"https://digital.nhs.uk/developer/api-catalogue/nhs-notify","description":"https://digital.nhs.uk/developer/api-catalogue/nhs-notify"}},"minProperties":1},"status":{"type":"string","enum":["401"],"example":"401"},"title":{"type":"string","enum":["Access denied"],"example":"Access denied"},"detail":{"type":"string","enum":["Access token missing, invalid or expired, or calling application not configured for this operation."],"example":"Access token missing, invalid or expired, or calling application not configured for this operation."},"source":{"type":"object","additionalProperties":false,"properties":{"header":{"type":"string","enum":["Authorization"],"example":"Authorization"}}}}}}}}},"application/json":{"schema":{"type":"object","title":"Access Denied","additionalProperties":false,"properties":{"errors":{"type":"array","minItems":1,"maxItems":1,"uniqueItems":true,"items":{"type":"object","additionalProperties":false,"properties":{"id":{"type":"string","title":"Type_ErrorIdentifier","description":"A system generated unique identifier for this request.","example":"rrt-1931948104716186917-c-geu2-10664-3111479-3.0"},"code":{"title":"Enum_Error_AccessDenied","type":"string","enum":["CM_DENIED"],"example":"CM_DENIED"},"links":{"type":"object","additionalProperties":false,"properties":{"about":{"type":"string","format":"uri","example":"https://digital.nhs.uk/developer/api-catalogue/nhs-notify","description":"https://digital.nhs.uk/developer/api-catalogue/nhs-notify"}},"minProperties":1},"status":{"type":"string","enum":["401"],"example":"401"},"title":{"type":"string","enum":["Access denied"],"example":"Access denied"},"detail":{"type":"string","enum":["Access token missing, invalid or expired, or calling application not configured for this operation."],"example":"Access token missing, invalid or expired, or calling application not configured for this operation."},"source":{"type":"object","additionalProperties":false,"properties":{"header":{"type":"string","enum":["Authorization"],"example":"Authorization"}}}}}}}}}},"headers":{"X-Correlation-ID":{"schema":{"type":"string","pattern":"11C46F5F-CDEF-4865-94B2-0EE0EDCC26DA","description":"If the X-Correlation-ID header was included in the request the value of this header will be equal to that. Otherwise it will be a unique alphanumeric string generated by NHS Notify."}}}},"403":{"description":"Your request contained an authentic bearer token in the `Authorization` header but you are not authorized to make the request.\n\nIf the error code in the response is `CM_FORBIDDEN` then this could be due to the onboarding process not having been completed. Refer to our [onboarding](#overview--onboarding) section for more information.\n\nIf the response contains the error `CM_SERVICE_BAN` then there is a ban in effect on your account.\n\n### Sandbox\n\nIt is possible to trigger the `CM_FORBIDDEN` error in the sandbox by sending the header `Prefer` with a value of `code=403`.\n\nHere is an example curl request to trigger a `CM_FORBIDDEN`:\n\n```\n curl -X GET \\\n --header \"Accept: */*\" \\\n --header \"Prefer: code=403\" \\\n https://sandbox.api.service.nhs.uk/comms/\n```\n\nTo trigger the `CM_SERVICE_BAN` error in the sandbox by sending the header `Prefer` with a value of `code=403.1`.\n\nHere is an example curl request to trigger a `CM_SERVICE_BAN`:\n\n```\n curl -X GET \\\n --header \"Accept: */*\" \\\n --header \"Prefer: code=403.1\" \\\n https://sandbox.api.service.nhs.uk/comms/\n```\n","content":{"application/vnd.api+json":{"schema":{"type":"object","title":"Forbidden","additionalProperties":false,"properties":{"errors":{"type":"array","minItems":1,"maxItems":1,"uniqueItems":true,"items":{"type":"object","additionalProperties":false,"properties":{"id":{"type":"string","title":"Type_ErrorIdentifier","description":"A system generated unique identifier for this request.","example":"rrt-1931948104716186917-c-geu2-10664-3111479-3.0"},"code":{"title":"Enum_Error_Forbidden","type":"string","enum":["CM_FORBIDDEN","CM_SERVICE_BAN"],"example":"CM_FORBIDDEN"},"links":{"type":"object","additionalProperties":false,"properties":{"about":{"type":"string","format":"uri","example":"https://digital.nhs.uk/developer/api-catalogue/nhs-notify","description":"https://digital.nhs.uk/developer/api-catalogue/nhs-notify"}},"minProperties":1},"status":{"type":"string","enum":["403"],"example":"403"},"title":{"type":"string","enum":["Forbidden","Service ban in effect"],"example":"Forbidden"},"detail":{"type":"string","enum":["Client not recognised or not yet onboarded.","A service ban is in effect on your account."],"example":"Client not recognised or not yet onboarded."},"source":{"type":"object","additionalProperties":false,"properties":{"header":{"type":"string","enum":["Authorization"],"example":"Authorization"}}}}}}}}},"application/json":{"schema":{"type":"object","title":"Forbidden","additionalProperties":false,"properties":{"errors":{"type":"array","minItems":1,"maxItems":1,"uniqueItems":true,"items":{"type":"object","additionalProperties":false,"properties":{"id":{"type":"string","title":"Type_ErrorIdentifier","description":"A system generated unique identifier for this request.","example":"rrt-1931948104716186917-c-geu2-10664-3111479-3.0"},"code":{"title":"Enum_Error_Forbidden","type":"string","enum":["CM_FORBIDDEN","CM_SERVICE_BAN"],"example":"CM_FORBIDDEN"},"links":{"type":"object","additionalProperties":false,"properties":{"about":{"type":"string","format":"uri","example":"https://digital.nhs.uk/developer/api-catalogue/nhs-notify","description":"https://digital.nhs.uk/developer/api-catalogue/nhs-notify"}},"minProperties":1},"status":{"type":"string","enum":["403"],"example":"403"},"title":{"type":"string","enum":["Forbidden","Service ban in effect"],"example":"Forbidden"},"detail":{"type":"string","enum":["Client not recognised or not yet onboarded.","A service ban is in effect on your account."],"example":"Client not recognised or not yet onboarded."},"source":{"type":"object","additionalProperties":false,"properties":{"header":{"type":"string","enum":["Authorization"],"example":"Authorization"}}}}}}}}}},"headers":{"X-Correlation-ID":{"schema":{"type":"string","pattern":"11C46F5F-CDEF-4865-94B2-0EE0EDCC26DA","description":"If the X-Correlation-ID header was included in the request the value of this header will be equal to that. Otherwise it will be a unique alphanumeric string generated by NHS Notify."}}}},"404":{"description":"The requested page has not been found, check the ODS code and page boundaries for any errors and try again.\n\n### Sandbox\n\nOn sandbox it is possible to simulate a 404 not found error using the `Prefer` header with a value of `code=404`.\n\nHere is an example curl request to trigger a `404`:\n\n```\n curl -X GET \\\n --header \"Accept: */*\" \\\n --header \"Content-type: application/vnd.api+json\" \\\n --header \"Prefer: code=404\" \\\n https://sandbox.api.service.nhs.uk/comms\n```\n","content":{"application/vnd.api+json":{"schema":{"type":"object","title":"Not found","additionalProperties":false,"properties":{"errors":{"type":"array","minItems":1,"maxItems":1,"uniqueItems":true,"items":{"type":"object","additionalProperties":false,"properties":{"id":{"type":"string","title":"Type_ErrorIdentifier","description":"A system generated unique identifier for this request.","example":"rrt-1931948104716186917-c-geu2-10664-3111479-3.0"},"code":{"title":"Enum_Error_NotFound","type":"string","enum":["CM_NOT_FOUND"],"example":"CM_NOT_FOUND"},"links":{"type":"object","additionalProperties":false,"properties":{"about":{"type":"string","format":"uri","example":"https://digital.nhs.uk/developer/api-catalogue/nhs-notify","description":"https://digital.nhs.uk/developer/api-catalogue/nhs-notify"}},"minProperties":1},"status":{"type":"string","enum":["404"],"example":"404"},"title":{"type":"string","enum":["Resource not found"],"example":"Resource not found"},"detail":{"type":"string","enum":["The resource at the requested URI was not found."],"example":"The resource at the requested URI was not found."}}}}}}},"application/json":{"schema":{"type":"object","title":"Not found","additionalProperties":false,"properties":{"errors":{"type":"array","minItems":1,"maxItems":1,"uniqueItems":true,"items":{"type":"object","additionalProperties":false,"properties":{"id":{"type":"string","title":"Type_ErrorIdentifier","description":"A system generated unique identifier for this request.","example":"rrt-1931948104716186917-c-geu2-10664-3111479-3.0"},"code":{"title":"Enum_Error_NotFound","type":"string","enum":["CM_NOT_FOUND"],"example":"CM_NOT_FOUND"},"links":{"type":"object","additionalProperties":false,"properties":{"about":{"type":"string","format":"uri","example":"https://digital.nhs.uk/developer/api-catalogue/nhs-notify","description":"https://digital.nhs.uk/developer/api-catalogue/nhs-notify"}},"minProperties":1},"status":{"type":"string","enum":["404"],"example":"404"},"title":{"type":"string","enum":["Resource not found"],"example":"Resource not found"},"detail":{"type":"string","enum":["The resource at the requested URI was not found."],"example":"The resource at the requested URI was not found."}}}}}}}},"headers":{"X-Correlation-ID":{"schema":{"type":"string","pattern":"11C46F5F-CDEF-4865-94B2-0EE0EDCC26DA","description":"If the X-Correlation-ID header was included in the request the value of this header will be equal to that. Otherwise it will be a unique alphanumeric string generated by NHS Notify."}}}},"405":{"description":"Your request specified a method that was not allowed on this endpoint.\n\nEndpoints only allow certain methods to be called on them. If your method was not one of the allowed ones it will be rejected with this status code.\n\n","content":{"application/vnd.api+json":{"schema":{"type":"object","title":"Method not allowed","additionalProperties":false,"properties":{"errors":{"type":"array","minItems":1,"maxItems":1,"uniqueItems":true,"items":{"type":"object","additionalProperties":false,"properties":{"id":{"type":"string","title":"Type_ErrorIdentifier","description":"A system generated unique identifier for this request.","example":"rrt-1931948104716186917-c-geu2-10664-3111479-3.0"},"code":{"title":"Enum_Error_Method_Not_Allowed","type":"string","enum":["CM_NOT_ALLOWED"],"example":"CM_NOT_ALLOWED"},"links":{"type":"object","additionalProperties":false,"properties":{"about":{"type":"string","format":"uri","example":"https://digital.nhs.uk/developer/api-catalogue/nhs-notify","description":"https://digital.nhs.uk/developer/api-catalogue/nhs-notify"}},"minProperties":1},"status":{"type":"string","enum":["405"],"example":"405"},"title":{"type":"string","enum":["Method not allowed"],"example":"Method not allowed"},"detail":{"type":"string","enum":["The method at the requested URI was not allowed."],"example":"The method at the requested URI was not allowed."}}}}}}},"application/json":{"schema":{"type":"object","title":"Method not allowed","additionalProperties":false,"properties":{"errors":{"type":"array","minItems":1,"maxItems":1,"uniqueItems":true,"items":{"type":"object","additionalProperties":false,"properties":{"id":{"type":"string","title":"Type_ErrorIdentifier","description":"A system generated unique identifier for this request.","example":"rrt-1931948104716186917-c-geu2-10664-3111479-3.0"},"code":{"title":"Enum_Error_Method_Not_Allowed","type":"string","enum":["CM_NOT_ALLOWED"],"example":"CM_NOT_ALLOWED"},"links":{"type":"object","additionalProperties":false,"properties":{"about":{"type":"string","format":"uri","example":"https://digital.nhs.uk/developer/api-catalogue/nhs-notify","description":"https://digital.nhs.uk/developer/api-catalogue/nhs-notify"}},"minProperties":1},"status":{"type":"string","enum":["405"],"example":"405"},"title":{"type":"string","enum":["Method not allowed"],"example":"Method not allowed"},"detail":{"type":"string","enum":["The method at the requested URI was not allowed."],"example":"The method at the requested URI was not allowed."}}}}}}}},"headers":{"X-Correlation-ID":{"schema":{"type":"string","pattern":"11C46F5F-CDEF-4865-94B2-0EE0EDCC26DA","description":"If the X-Correlation-ID header was included in the request the value of this header will be equal to that. Otherwise it will be a unique alphanumeric string generated by NHS Notify."}}}},"406":{"description":"The request did not contain a valid `Accept` header value.\n\nValid values are:\n\n* `*/*`\n* `application/json`\n* `application/vnd.api+json`\n* `application/json; charset=utf-8`\n* `application/vnd.api+json; charset=utf-8`\n\nWhere no `Accept` header is present, this will default to `application/vnd.api+json`\n","content":{"application/vnd.api+json":{"schema":{"type":"object","title":"Not Acceptable","additionalProperties":false,"properties":{"errors":{"type":"array","minItems":1,"maxItems":1,"uniqueItems":true,"items":{"type":"object","additionalProperties":false,"properties":{"id":{"type":"string","title":"Type_ErrorIdentifier","description":"A system generated unique identifier for this request.","example":"rrt-1931948104716186917-c-geu2-10664-3111479-3.0"},"code":{"title":"Enum_Error_NotAcceptable","type":"string","enum":["CM_NOT_ACCEPTABLE"],"example":"CM_NOT_ACCEPTABLE"},"links":{"type":"object","additionalProperties":false,"properties":{"about":{"type":"string","format":"uri","example":"https://digital.nhs.uk/developer/api-catalogue/nhs-notify","description":"https://digital.nhs.uk/developer/api-catalogue/nhs-notify"}},"minProperties":1},"status":{"type":"string","enum":["406"],"example":"406"},"title":{"type":"string","enum":["Not acceptable"],"example":"Not acceptable"},"detail":{"type":"string","enum":["This service can only generate application/vnd.api+json or application/json."],"example":"This service can only generate application/vnd.api+json or application/json."},"source":{"type":"object","additionalProperties":false,"properties":{"header":{"type":"string","enum":["Accept"],"example":"Accept"}}}}}}}}}},"headers":{"X-Correlation-ID":{"schema":{"type":"string","pattern":"11C46F5F-CDEF-4865-94B2-0EE0EDCC26DA","description":"If the X-Correlation-ID header was included in the request the value of this header will be equal to that. Otherwise it will be a unique alphanumeric string generated by NHS Notify."}}}},"408":{"description":"There has been a client side issue reading your request. This can occur when there are networking issues between your application and our service.\n\nThere may also be an issue within our backend where a `408` has been bubbled up and exposed.\n\nThis could be indicative of an ongoing infrastructure issue that is out of our (or your) control.\n\n### Sandbox\n\nIt is possible to simulate this error response by sending a request with a header of `Prefer` set to the value `code=408`.\n\nHere is an example curl request to simulate this response:\n\n```\n curl -X GET --header \"Prefer: code=408\" https://sandbox.api.service.nhs.uk/comms/\n```\n\n","content":{"application/vnd.api+json":{"schema":{"type":"object","title":"Request timeout","additionalProperties":false,"properties":{"errors":{"type":"array","minItems":1,"maxItems":1,"uniqueItems":true,"items":{"type":"object","additionalProperties":false,"properties":{"id":{"type":"string","title":"Type_ErrorIdentifier","description":"A system generated unique identifier for this request.","example":"rrt-1931948104716186917-c-geu2-10664-3111479-3.0"},"code":{"title":"Enum_Error_Timeout","type":"string","enum":["CM_TIMEOUT"],"example":"CM_TIMEOUT"},"links":{"type":"object","additionalProperties":false,"properties":{"about":{"type":"string","format":"uri","example":"https://digital.nhs.uk/developer/api-catalogue/nhs-notify","description":"https://digital.nhs.uk/developer/api-catalogue/nhs-notify"}},"minProperties":1},"status":{"type":"string","enum":["408"],"example":"408"},"title":{"type":"string","enum":["Request timeout"],"example":"Request timeout"},"detail":{"type":"string","enum":["The service was unable to receive your request within the timeout period."],"example":"The service was unable to receive your request within the timeout period."}}}}}}},"application/json":{"schema":{"type":"object","title":"Request timeout","additionalProperties":false,"properties":{"errors":{"type":"array","minItems":1,"maxItems":1,"uniqueItems":true,"items":{"type":"object","additionalProperties":false,"properties":{"id":{"type":"string","title":"Type_ErrorIdentifier","description":"A system generated unique identifier for this request.","example":"rrt-1931948104716186917-c-geu2-10664-3111479-3.0"},"code":{"title":"Enum_Error_Timeout","type":"string","enum":["CM_TIMEOUT"],"example":"CM_TIMEOUT"},"links":{"type":"object","additionalProperties":false,"properties":{"about":{"type":"string","format":"uri","example":"https://digital.nhs.uk/developer/api-catalogue/nhs-notify","description":"https://digital.nhs.uk/developer/api-catalogue/nhs-notify"}},"minProperties":1},"status":{"type":"string","enum":["408"],"example":"408"},"title":{"type":"string","enum":["Request timeout"],"example":"Request timeout"},"detail":{"type":"string","enum":["The service was unable to receive your request within the timeout period."],"example":"The service was unable to receive your request within the timeout period."}}}}}}}},"headers":{"X-Correlation-ID":{"schema":{"type":"string","pattern":"11C46F5F-CDEF-4865-94B2-0EE0EDCC26DA","description":"If the X-Correlation-ID header was included in the request the value of this header will be equal to that. Otherwise it will be a unique alphanumeric string generated by NHS Notify."}}}},"429":{"description":"This endpoint is currently receiving a high volume of requests and is being rate limited.\n\nIf you have a retry mechanism in your HTTP client you may want to look at implementing an [exponential backoff](https://en.wikipedia.org/wiki/Exponential_backoff).\n\n### Sandbox\n\nIt is possible to trigger this on the sandbox by using the `Prefer` header with a value of `code=429`.\n\nHere is an example curl request to trigger a `429`:\n\n```\n curl -X GET --header \"Prefer: code=429\" https://sandbox.api.service.nhs.uk/comms/\n```\n","content":{"application/vnd.api+json":{"schema":{"type":"object","title":"Too many requests","additionalProperties":false,"properties":{"errors":{"type":"array","minItems":1,"maxItems":1,"uniqueItems":true,"items":{"type":"object","additionalProperties":false,"properties":{"id":{"type":"string","title":"Type_ErrorIdentifier","description":"A system generated unique identifier for this request.","example":"rrt-1931948104716186917-c-geu2-10664-3111479-3.0"},"code":{"title":"Enum_Error_Quota","type":"string","enum":["CM_QUOTA"],"example":"CM_QUOTA"},"links":{"type":"object","additionalProperties":false,"properties":{"about":{"type":"string","format":"uri","example":"https://digital.nhs.uk/developer/api-catalogue/nhs-notify","description":"https://digital.nhs.uk/developer/api-catalogue/nhs-notify"}},"minProperties":1},"status":{"type":"string","enum":["429"],"example":"429"},"title":{"type":"string","enum":["Too many requests"],"example":"Too many requests"},"detail":{"type":"string","enum":["This endpoint is currently receiving a high volume of requests and is being rate limited."],"example":"This endpoint is currently receiving a high volume of requests and is being rate limited."}}}}}}},"application/json":{"schema":{"type":"object","title":"Too many requests","additionalProperties":false,"properties":{"errors":{"type":"array","minItems":1,"maxItems":1,"uniqueItems":true,"items":{"type":"object","additionalProperties":false,"properties":{"id":{"type":"string","title":"Type_ErrorIdentifier","description":"A system generated unique identifier for this request.","example":"rrt-1931948104716186917-c-geu2-10664-3111479-3.0"},"code":{"title":"Enum_Error_Quota","type":"string","enum":["CM_QUOTA"],"example":"CM_QUOTA"},"links":{"type":"object","additionalProperties":false,"properties":{"about":{"type":"string","format":"uri","example":"https://digital.nhs.uk/developer/api-catalogue/nhs-notify","description":"https://digital.nhs.uk/developer/api-catalogue/nhs-notify"}},"minProperties":1},"status":{"type":"string","enum":["429"],"example":"429"},"title":{"type":"string","enum":["Too many requests"],"example":"Too many requests"},"detail":{"type":"string","enum":["This endpoint is currently receiving a high volume of requests and is being rate limited."],"example":"This endpoint is currently receiving a high volume of requests and is being rate limited."}}}}}}}},"headers":{"X-Correlation-ID":{"schema":{"type":"string","pattern":"11C46F5F-CDEF-4865-94B2-0EE0EDCC26DA","description":"If the X-Correlation-ID header was included in the request the value of this header will be equal to that. Otherwise it will be a unique alphanumeric string generated by NHS Notify."}}}},"500":{"description":"An error has occured that is stopping your request from being processed.\n\n### Sandbox\n\nIt is possible to trigger the `CM_INTERNAL_SERVER_ERROR` on the sandbox by using the `Prefer` header with a value of `code=500`.\n\nHere is an example curl request to trigger a `500`:\n\n```\n curl -X GET --header \"Prefer: code=500\" https://sandbox.api.service.nhs.uk/comms\n```\n","content":{"application/vnd.api+json":{"schema":{"type":"object","title":"Internal server error","additionalProperties":false,"properties":{"errors":{"type":"array","minItems":1,"uniqueItems":true,"items":{"type":"object","additionalProperties":false,"properties":{"id":{"type":"string","title":"Type_ErrorIdentifier","description":"A system generated unique identifier for this request.","example":"rrt-1931948104716186917-c-geu2-10664-3111479-3.0"},"code":{"title":"Enum_Error_InternalServerError","type":"string","enum":["CM_INTERNAL_SERVER_ERROR"],"example":"CM_INTERNAL_SERVER_ERROR"},"links":{"type":"object","additionalProperties":false,"properties":{"about":{"type":"string","format":"uri","example":"https://digital.nhs.uk/developer/api-catalogue/nhs-notify","description":"https://digital.nhs.uk/developer/api-catalogue/nhs-notify"}},"minProperties":1},"status":{"type":"string","enum":["500"],"example":"500"},"title":{"type":"string","enum":["Error processing request"],"example":"Error processing request"},"detail":{"type":"string","enum":["There was an internal error whilst processing this request."],"example":"There was an internal error whilst processing this request."}}}}}}},"application/json":{"schema":{"type":"object","title":"Internal server error","additionalProperties":false,"properties":{"errors":{"type":"array","minItems":1,"uniqueItems":true,"items":{"type":"object","additionalProperties":false,"properties":{"id":{"type":"string","title":"Type_ErrorIdentifier","description":"A system generated unique identifier for this request.","example":"rrt-1931948104716186917-c-geu2-10664-3111479-3.0"},"code":{"title":"Enum_Error_InternalServerError","type":"string","enum":["CM_INTERNAL_SERVER_ERROR"],"example":"CM_INTERNAL_SERVER_ERROR"},"links":{"type":"object","additionalProperties":false,"properties":{"about":{"type":"string","format":"uri","example":"https://digital.nhs.uk/developer/api-catalogue/nhs-notify","description":"https://digital.nhs.uk/developer/api-catalogue/nhs-notify"}},"minProperties":1},"status":{"type":"string","enum":["500"],"example":"500"},"title":{"type":"string","enum":["Error processing request"],"example":"Error processing request"},"detail":{"type":"string","enum":["There was an internal error whilst processing this request."],"example":"There was an internal error whilst processing this request."}}}}}}}},"headers":{"X-Correlation-ID":{"schema":{"type":"string","pattern":"11C46F5F-CDEF-4865-94B2-0EE0EDCC26DA","description":"If the X-Correlation-ID header was included in the request the value of this header will be equal to that. Otherwise it will be a unique alphanumeric string generated by NHS Notify."}}}},"502":{"description":"NHS Notify is currently unable to communicate with a downstream API required to process your request.\n\n### Sandbox\n\nIt is possible to trigger the `CM_BAD_GATEWAY` on the sandbox by using the `Prefer` header with a value of `code=502`.\n\nHere is an example curl request to trigger a `502`:\n\n```\n curl -X GET --header \"Prefer: code=502\" https://sandbox.api.service.nhs.uk/comms\n```\n","content":{"application/vnd.api+json":{"schema":{"type":"object","title":"Bad gateway","additionalProperties":false,"properties":{"errors":{"type":"array","minItems":1,"maxItems":1,"uniqueItems":true,"items":{"type":"object","additionalProperties":false,"properties":{"id":{"type":"string","title":"Type_ErrorIdentifier","description":"A system generated unique identifier for this request.","example":"rrt-1931948104716186917-c-geu2-10664-3111479-3.0"},"code":{"title":"Enum_Error_BadGateway","type":"string","enum":["CM_BAD_GATEWAY"],"example":"CM_BAD_GATEWAY"},"links":{"type":"object","additionalProperties":false,"properties":{"about":{"type":"string","format":"uri","example":"https://digital.nhs.uk/developer/api-catalogue/nhs-notify","description":"https://digital.nhs.uk/developer/api-catalogue/nhs-notify"}},"minProperties":1},"status":{"type":"string","enum":["502"],"example":"502"},"title":{"type":"string","enum":["Unable to call service"],"example":"Unable to call service"},"detail":{"type":"string","enum":["A downstream service is not responding."],"example":"A downstream service is not responding."}}}}}}},"application/json":{"schema":{"type":"object","title":"Bad gateway","additionalProperties":false,"properties":{"errors":{"type":"array","minItems":1,"maxItems":1,"uniqueItems":true,"items":{"type":"object","additionalProperties":false,"properties":{"id":{"type":"string","title":"Type_ErrorIdentifier","description":"A system generated unique identifier for this request.","example":"rrt-1931948104716186917-c-geu2-10664-3111479-3.0"},"code":{"title":"Enum_Error_BadGateway","type":"string","enum":["CM_BAD_GATEWAY"],"example":"CM_BAD_GATEWAY"},"links":{"type":"object","additionalProperties":false,"properties":{"about":{"type":"string","format":"uri","example":"https://digital.nhs.uk/developer/api-catalogue/nhs-notify","description":"https://digital.nhs.uk/developer/api-catalogue/nhs-notify"}},"minProperties":1},"status":{"type":"string","enum":["502"],"example":"502"},"title":{"type":"string","enum":["Unable to call service"],"example":"Unable to call service"},"detail":{"type":"string","enum":["A downstream service is not responding."],"example":"A downstream service is not responding."}}}}}}}},"headers":{"X-Correlation-ID":{"schema":{"type":"string","pattern":"11C46F5F-CDEF-4865-94B2-0EE0EDCC26DA","description":"If the X-Correlation-ID header was included in the request the value of this header will be equal to that. Otherwise it will be a unique alphanumeric string generated by NHS Notify."}}}},"503":{"description":"The service is currently not accepting requests,\n\nThis error can occur if any part of the system has gone offline.\n\n### Sandbox\n\nIt is possible to simulate this error response by sending a request with a header of `Prefer` set to the value `code=503`.\n\nHere is an example curl request to simulate this response:\n\n```\n curl -X GET --header \"Prefer: code=503\" https://sandbox.api.service.nhs.uk/comms/\n```\n","content":{"application/vnd.api+json":{"schema":{"type":"object","title":"Service unavailable","additionalProperties":false,"properties":{"errors":{"type":"array","minItems":1,"maxItems":1,"uniqueItems":true,"items":{"type":"object","additionalProperties":false,"properties":{"id":{"type":"string","title":"Type_ErrorIdentifier","description":"A system generated unique identifier for this request.","example":"rrt-1931948104716186917-c-geu2-10664-3111479-3.0"},"code":{"title":"Enum_Error_ServiceUnavailable","type":"string","enum":["CM_SERVICE_UNAVAILABLE"],"example":"CM_SERVICE_UNAVAILABLE"},"links":{"type":"object","additionalProperties":false,"properties":{"about":{"type":"string","format":"uri","example":"https://digital.nhs.uk/developer/api-catalogue/nhs-notify","description":"https://digital.nhs.uk/developer/api-catalogue/nhs-notify"}},"minProperties":1},"status":{"type":"string","enum":["503"],"example":"503"},"title":{"type":"string","enum":["The service is currently unavailable"],"example":"The service is currently unavailable"},"detail":{"type":"string","enum":["The service is currently not able to process this request, try again later."],"example":"The service is currently not able to process this request, try again later."}}}}}}},"application/json":{"schema":{"type":"object","title":"Service unavailable","additionalProperties":false,"properties":{"errors":{"type":"array","minItems":1,"maxItems":1,"uniqueItems":true,"items":{"type":"object","additionalProperties":false,"properties":{"id":{"type":"string","title":"Type_ErrorIdentifier","description":"A system generated unique identifier for this request.","example":"rrt-1931948104716186917-c-geu2-10664-3111479-3.0"},"code":{"title":"Enum_Error_ServiceUnavailable","type":"string","enum":["CM_SERVICE_UNAVAILABLE"],"example":"CM_SERVICE_UNAVAILABLE"},"links":{"type":"object","additionalProperties":false,"properties":{"about":{"type":"string","format":"uri","example":"https://digital.nhs.uk/developer/api-catalogue/nhs-notify","description":"https://digital.nhs.uk/developer/api-catalogue/nhs-notify"}},"minProperties":1},"status":{"type":"string","enum":["503"],"example":"503"},"title":{"type":"string","enum":["The service is currently unavailable"],"example":"The service is currently unavailable"},"detail":{"type":"string","enum":["The service is currently not able to process this request, try again later."],"example":"The service is currently not able to process this request, try again later."}}}}}}}},"headers":{"Retry-After":{"schema":{"type":"integer","minimum":5,"multipleOf":1,"example":5},"description":"Time to wait between requests in seconds."},"X-Correlation-ID":{"schema":{"type":"string","pattern":"11C46F5F-CDEF-4865-94B2-0EE0EDCC26DA","description":"If the X-Correlation-ID header was included in the request the value of this header will be equal to that. Otherwise it will be a unique alphanumeric string generated by NHS Notify."}}}},"504":{"description":"There is an issue communicating to our backend services. If this occurs it is a good idea to back off and retry the request at a later time - see the [Circuit Breaker pattern](https://microservices.io/patterns/reliability/circuit-breaker.html).\n\nThis error can occur if there is an issue with a dependent service and so may be bubbled up from a 3rd party HTTP call.\n\n### Sandbox\n\nIt is possible to simulate this error response by sending a request with a header of `Prefer` set to the value `code=504`.\n\nHere is an example curl request to simulate this response:\n\n```\n curl -X GET --header \"Prefer: code=504\" https://sandbox.api.service.nhs.uk/comms/\n```\n\nTo simulate a backend `504` exception bubbling upwards you can send this request:\n\n```\n curl -X GET https://sandbox.api.service.nhs.uk/comms/_timeout_504\n```\n","content":{"application/vnd.api+json":{"schema":{"type":"object","title":"Service timeout","additionalProperties":false,"properties":{"errors":{"type":"array","minItems":1,"maxItems":1,"uniqueItems":true,"items":{"type":"object","additionalProperties":false,"properties":{"id":{"type":"string","title":"Type_ErrorIdentifier","description":"A system generated unique identifier for this request.","example":"rrt-1931948104716186917-c-geu2-10664-3111479-3.0"},"code":{"title":"Enum_Error_Timeout","type":"string","enum":["CM_TIMEOUT"],"example":"CM_TIMEOUT"},"links":{"type":"object","additionalProperties":false,"properties":{"about":{"type":"string","format":"uri","example":"https://digital.nhs.uk/developer/api-catalogue/nhs-notify","description":"https://digital.nhs.uk/developer/api-catalogue/nhs-notify"}},"minProperties":1},"status":{"type":"string","enum":["504"],"example":"504"},"title":{"type":"string","enum":["Unable to call service"],"example":"Unable to call service"},"detail":{"type":"string","enum":["The downstream service has not responded within the configured timeout period."],"example":"The downstream service has not responded within the configured timeout period."}}}}}}},"application/json":{"schema":{"type":"object","title":"Service timeout","additionalProperties":false,"properties":{"errors":{"type":"array","minItems":1,"maxItems":1,"uniqueItems":true,"items":{"type":"object","additionalProperties":false,"properties":{"id":{"type":"string","title":"Type_ErrorIdentifier","description":"A system generated unique identifier for this request.","example":"rrt-1931948104716186917-c-geu2-10664-3111479-3.0"},"code":{"title":"Enum_Error_Timeout","type":"string","enum":["CM_TIMEOUT"],"example":"CM_TIMEOUT"},"links":{"type":"object","additionalProperties":false,"properties":{"about":{"type":"string","format":"uri","example":"https://digital.nhs.uk/developer/api-catalogue/nhs-notify","description":"https://digital.nhs.uk/developer/api-catalogue/nhs-notify"}},"minProperties":1},"status":{"type":"string","enum":["504"],"example":"504"},"title":{"type":"string","enum":["Unable to call service"],"example":"Unable to call service"},"detail":{"type":"string","enum":["The downstream service has not responded within the configured timeout period."],"example":"The downstream service has not responded within the configured timeout period."}}}}}}}},"headers":{"X-Correlation-ID":{"schema":{"type":"string","pattern":"11C46F5F-CDEF-4865-94B2-0EE0EDCC26DA","description":"If the X-Correlation-ID header was included in the request the value of this header will be equal to that. Otherwise it will be a unique alphanumeric string generated by NHS Notify."}}}}}}},"/":{"post":{"tags":["Callbacks"],"summary":"Message status","description":"\nMessage status callbacks send POST requests to your service with real time updates when the status of a message has changed.\n\nThis is an automated way to get the status of messages.\n\nFind out more about message statuses and which statuses you can receive (opens in a new tab).\n\nIf you're onboarding with NHS Notify and need to use the channel and supplier status callback, contact the onboarding team to tell them what statuses you want to subscribe to.\n\nIf you're live with NHS Notify and need to use the channel and supplier status callback, [raise a Service Now ticket](https://nhsdigitallive.service-now.com/csm).\n\n### Deciding which message status callbacks to receive\n\nIt's your organisation or service's responsibility to decide which statuses to receive callbacks for.\n\nThe message status callbacks are typically used for finding out if a recipient has been contacted with any of the channels in a routing plan.\n\nFor example, if you only want updating when your patients have been contacted and do not need updating when each message channel was used, choose the `delivered` and `failed` message statuses.\n\nIf you need additional real time updates when the status of a channel changes, you can also use the channel and supplier status callback.","operationId":"post-v1-message-callbacks","parameters":[{"name":"x-hmac-sha256-signature","in":"header","description":"Contains a HMAC-SHA256 signature of the request body using a pre-agreed secret","schema":{"type":"string","example":"9ee8c6aab877a97600e5c0cd8419f52d3dcdc45002e35220873d11123db6486f"}},{"name":"x-api-key","in":"header","description":"Contains the pre-agreed API key.","schema":{"type":"string","example":"0bb04a0e-d005-42dd-8993-dacf37410a12"}}],"requestBody":{"content":{"application/vnd.api+json":{"schema":{"type":"object","properties":{"data":{"type":"array","minItems":1,"items":{"type":"object","title":"CallbackRequest","properties":{"type":{"type":"string","example":"MessageStatus","enum":["MessageStatus"]},"attributes":{"type":"object","properties":{"messageId":{"type":"string","title":"Type_KSUID","description":"The unique identifier for the message.","pattern":"^[a-zA-Z0-9]{27}$","minLength":27,"maxLength":27,"example":"2WL3qFTEFM0qMY8xjRbt1LIKCzM"},"messageReference":{"type":"string","description":"Original reference supplied for the message.","example":"1642109b-69eb-447f-8f97-ab70a74f5db4"},"messageStatus":{"title":"Enum_MessageStatus","description":"An overall aggregate status taken from all of the communication channels that we have attempted to deliver the message using.","type":"string","enum":["created","pending_enrichment","enriched","sending","delivered","failed"],"example":"sending"},"messageStatusDescription":{"type":"string","description":"If there is extra information associated with the status of this message, it is provided here.","example":"Failed reason: Contact detail is missing"},"messageFailureReasonCode":{"type":"string","description":"If there is a failed reason code associated with this message, it is provided here.","example":"MFR_PDSV_0002"},"channels":{"type":"array","minItems":0,"items":{"type":"object","properties":{"type":{"title":"Enum_ChannelType","description":"The communication type of this channel.","type":"string","enum":["nhsapp","email","sms","letter"],"example":"email"},"channelStatus":{"enum":["delivered","failed"],"title":"Enum_ChannelStatus","description":"The current status of this channel at the time this response was generated.","type":"string","example":"delivered"}}}},"timestamp":{"type":"string","description":"Timestamp of the callback event.","format":"date-time","example":"2023-11-17T14:27:51.413Z"},"routingPlan":{"type":"object","additionalProperties":false,"required":["id","name","createdDate"],"properties":{"id":{"type":"string","format":"uuid","description":"The identifier for the routing plan.","example":"b838b13c-f98c-4def-93f0-515d4e4f4ee1"},"name":{"type":"string","description":"The name of the routing plan.","example":"Plan Abc"},"version":{"type":"string","description":"This identifies the specific version of the routing plan.","example":"ztoe2qRAM8M8vS0bqajhyEBcvXacrGPp"},"createdDate":{"type":"string","description":"The creation date of the routing plan.","format":"date-time","example":"2023-11-17T14:27:51.413Z"}}},"metadata":{"type":"array","minItems":1,"items":{"type":"object","additionalProperties":false,"properties":{"version":{"type":"string","description":"The version identifier of the source data at the time it was queried","example":"2"},"queriedAt":{"type":"date-time","description":"The timestamp when the source was queried","example":"2023-11-17T14:27:51.413Z"},"source":{"type":"string","description":"This identifies the source of the metadata. This is a free text field and can be used to identify the system that provided the metadata.","example":"pds"}},"required":["queriedAt","source"]}}},"required":["messageId","messageReference","messageStatus","timestamp","routingPlan"]},"links":{"type":"object","properties":{"message":{"type":"string","description":"URL to retrieve overarching message status from the GET endpoint.","format":"uri","example":"https://api.service.nhs.uk/comms/v1/messages/2WL3qFTEFM0qMY8xjRbt1LIKCzM"}},"required":["message"]},"meta":{"type":"object","properties":{"idempotencyKey":{"type":"string","description":"Contains a value that you can use to deduplicate retried. requests.","example":"2515ae6b3a08339fba3534f3b17cd57cd573c57d25b25b9aae08e42dc9f0a445"}}}}}}}}}}},"responses":{"202":{"description":"Accepted"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"429":{"description":"If callbacks are being received at a faster rate than your client can process them, you can respond with a `429` status code to indicate that the callbacks should back-off and retry later. \nNHS Notify has a default retry policy which is exponential plus a randomised jitter. \nYour client may additionally provide the standard HTTP `Retry-After` response header to specify how long Notify should wait before retrying. NHS Notify will select the most conservative option between the standard retry policy and the `Retry-After` header. \nSend a negative value in the `Retry-After` header to stop retrying for that callback event.\n\n","headers":{"Retry-After":{"schema":{"type":"integer","format":"duration","minimum":5,"multipleOf":1,"example":5},"description":"Time to wait between requests in seconds"}}}}}},"/":{"post":{"tags":["Callbacks"],"summary":"Channel and supplier status","description":"The channel and supplier status callback sends POST requests to your service with real time updates when the status of a channel or supplier has changed.\n\nThis is an automated way to get the status of each channel used in a routing plan.\n\nFind out more about channel statuses and which statuses you can receive (opens in a new tab).\n\nFor more detailed statuses about specific channels, you can also receive supplier statuses.\n\nFind out more about supplier statuses and and which statuses you can receive (opens in a new tab).\n\nIf you're onboarding with NHS Notify and need to use the channel and supplier status callback, contact the onboarding team to tell them what statuses you want to subscribe to.\n\nIf you're live with NHS Notify and need to use the channel and supplier status callback, [raise a Service Now ticket](https://nhsdigitallive.service-now.com/csm).\n\n### Deciding which message status callbacks to receive\nIt's your organisation or service's responsibility to decide which statuses to receive callbacks for.\n\nYou may need to subscribe to a combination of channel and supplier statuses if you:\n\n- want to send your own fallback messages based on specific statuses\n- need to know exactly how a message has performed in real time with each of your recipients\n- need to know what happened to a message sent using a secondary cascade (opens in a new tab)","operationId":"post-v1-channel-callbacks","parameters":[{"name":"x-hmac-sha256-signature","in":"header","description":"Contains a HMAC-SHA256 signature of the request body using a pre-agreed secret","schema":{"type":"string","example":"9ee8c6aab877a97600e5c0cd8419f52d3dcdc45002e35220873d11123db6486f"}},{"name":"x-api-key","in":"header","description":"Contains the pre-agreed API key.","schema":{"type":"string","example":"0bb04a0e-d005-42dd-8993-dacf37410a12"}}],"requestBody":{"content":{"application/vnd.api+json":{"schema":{"type":"object","properties":{"data":{"type":"array","minItems":1,"items":{"type":"object","title":"CallbackRequest","required":["type","attributes","links","meta"],"properties":{"type":{"type":"string","example":"ChannelStatus","enum":["ChannelStatus"]},"attributes":{"type":"object","properties":{"messageId":{"type":"string","title":"Type_KSUID","description":"The unique identifier for the message.","pattern":"^[a-zA-Z0-9]{27}$","minLength":27,"maxLength":27,"example":"2WL3qFTEFM0qMY8xjRbt1LIKCzM"},"messageReference":{"type":"string","description":"Original reference supplied for the message.","example":"1642109b-69eb-447f-8f97-ab70a74f5db4"},"cascadeType":{"title":"Enum_CascadeType","description":"The cascade type of this message. You can set up primary or secondary message cascades in your routing plan. [Learn more about routing plans and message cascades](https://notify.nhs.uk/using-nhs-notify/routing-plans).","type":"string","enum":["primary","secondary"],"example":"primary"},"cascadeOrder":{"type":"integer","description":"The order of the message in your message cascade. The value is 1-based.","example":1},"channel":{"type":"string","enum":["nhsapp","sms","letter","email"],"example":"nhsapp"},"channelStatus":{"title":"Enum_ChannelStatus","description":"The current status of this channel at the time this response was generated.","type":"string","enum":["created","sending","delivered","failed","skipped"],"example":"delivered"},"channelStatusDescription":{"type":"string","description":"If there is extra information associated with the status of this channel, it is provided here.","example":"Failed reason: Contact detail is missing"},"channelFailureReasonCode":{"type":"string","description":"If there is a failed reason code associated with this channel, it is provided here.","example":"CFR_PDSV_0002"},"supplierStatus":{"title":"Enum_SupplierStatus","description":"The current status of this message within the channel at the time this response was generated.","type":"string","enum":["delivered","read","notification_attempted","unnotified","rejected","notified","received","permanent_failure","temporary_failure","technical_failure","accepted","cancelled","pending_virus_check","validation_failed","unknown"],"example":"delivered"},"timestamp":{"type":"string","description":"Date-time for when the supplier status change was processed.","format":"date-time","example":"2023-11-17T14:27:51.413Z"},"retryCount":{"type":"integer","description":"Contains the number of times that we have attempted to send this message to this channel. Only returned if sending is retried one or more times.","example":1},"metadata":{"type":"array","minItems":0,"description":"This array includes a list of all metadata lookups done for this channel within the system.\n\nCurrently only PDS is used for lookups.","items":{"type":"object","additionalProperties":false,"required":["source","label"],"properties":{"id":{"type":"string","description":"The sourceâs identifier for the metadata.","example":"y5z6a7b8"},"source":{"type":"string","description":"The source of the metadata.","example":"pds"},"label":{"title":"Enum_ChannelMetadataLabel","description":"The label associated with the metadata for this channel at the time this response was generated.","type":"string","enum":["recipient_contact"],"example":"recipient_contact"}}}}},"required":["messageId","messageReference","cascadeType","cascadeOrder","channel","channelStatus","timestamp","retryCount"]},"links":{"type":"object","properties":{"message":{"type":"string","description":"URL to retrieve overarching message status from the GET endpoint.","format":"uri","example":"https://api.service.nhs.uk/comms/v1/messages/2WL3qFTEFM0qMY8xjRbt1LIKCzM"}},"required":["message"]},"meta":{"type":"object","properties":{"idempotencyKey":{"type":"string","description":"Contains a value that you can use to deduplicate retried. requests.","example":"2515ae6b3a08339fba3534f3b17cd57cd573c57d25b25b9aae08e42dc9f0a445"}},"required":["idempotencyKey"]}}}}}}}}},"responses":{"202":{"description":"Accepted"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"429":{"description":"If callbacks are being received at a faster rate than your client can process them, you can respond with a `429` status code to indicate that the callbacks should back-off and retry later. \nNHS Notify has a default retry policy which is exponential plus a randomised jitter. \nYour client may additionally provide the standard HTTP `Retry-After` response header to specify how long Notify should wait before retrying. NHS Notify will select the most conservative option between the standard retry policy and the `Retry-After` header. \nSend a negative value in the `Retry-After` header to stop retrying for that callback event.\n\n","headers":{"Retry-After":{"schema":{"type":"integer","format":"duration","minimum":5,"multipleOf":1,"example":5},"description":"Time to wait between requests in seconds"}}}}}}}}