openapi: 3.0.0 info: version: '3.0' title: Communications Manager API description: | ## Overview Use this API to send messages to citizens via email, SMS, the NHS App or letter. Communications Manager provides: * message templating * message routing - via SMS, email, letter and NHS App * enrichment of recipient details * support for accessible formats For more information about this services capabilities, see [Communications Manager Service](https://digital.nhs.uk/services/communications-manager). ## Who can use this API The Communications Manager 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. ## API status and roadmap This API is [in development](https://digital.nhs.uk/developer/guides-and-documentation/reference-guide#statuses). You can comment, upvote and view progress on [our roadmap](https://nhs-digital-api-management.featureupvote.com/suggestions/355852/communications-manager-api). If you have any other queries, [contact us](https://digital.nhs.uk/developer/help-and-support). ## Service level The Communications Manager API is currently not in a production environment. For more details, see [service levels](https://digital.nhs.uk/developer/guides-and-documentation/reference-guide#service-levels). ## Technology This API is a [REST-based](https://digital.nhs.uk/developer/guides-and-documentation/our-api-technologies#basic-rest) API. We follow the [JSON:API](https://jsonapi.org/) standard for our request and response schemas. ### Response content types This API can generate responses in the following formats: * `application/vnd.api+json` - see [JSON:API specification](https://jsonapi.org/format/#introduction) * `application/json` Both of these formats have the same structure - the API responds with a standard JSON document. You can control which `Content-Type` is returned by using the `Accept` header. The `Accept` header can contain the following values: * `*/*` * `application/json` * `application/vnd.api+json` Where no `Accept` header is present, this will default to `application/vnd.api+json` ### Request Content Types This API will accept request payloads of the following types: * `application/vnd.api+json` - see [JSON:API specification](https://jsonapi.org/format/#introduction) * `application/json` If you attempt to send a payload without the `Content-Type` header set to either of these values then the API will respond with a `415 Unsupported Media Type` response. ## Network access This API is available on the internet and, indirectly on the [Health and Social Care Network (HSCN)](https://digital.nhs.uk/services/health-and-social-care-network). For more details see [Network access for APIs](https://digital.nhs.uk/developer/guides-and-documentation/network-access-for-apis). ## Security and authorisation This API is [application-restricted](https://digital.nhs.uk/developer/guides-and-documentation/security-and-authorisation#application-restricted-apis), meaning we authenticate the calling application but not the end user. Authentication and authorisation of end users is the responsibility of your application. To access this API, use the following security pattern: * [Application-restricted RESTful API - signed JWT authentication](https://digital.nhs.uk/developer/guides-and-documentation/security-and-authorisation/application-restricted-restful-apis-signed-jwt-authentication) ## Environments and testing | Environment | Base URL | |------------ | -------- | | Sandbox | [https://sandbox.api.service.nhs.uk/comms](https://sandbox.api.service.nhs.uk/comms) | | Integration test | [https://int.api.service.nhs.uk/comms](https://int.api.service.nhs.uk/comms) | | Production | Not yet available | ### Sandbox testing Our [sandbox environment](https://digital.nhs.uk/developer/guides-and-documentation/testing#sandbox-testing): * is for early developer testing * only covers a limited set of scenarios * is stateless, so does not actually persist any updates * is open access, so does not allow you to test authorisation For details of sandbox test scenarios, or to try out sandbox using our our 'Try this API' feature, see the documentation for each endpoint. Alternatively, you can try out the sandbox using our Postman collection: [![Run in Postman](https://run.pstmn.io/button.svg)](https://god.gw.postman.com/run-collection/28740466-ec078d1e-d4d7-4460-92b9-7d79d51f967a?action=collection%2Ffork&source=rip_markdown&collection-url=entityId%3D28740466-ec078d1e-d4d7-4460-92b9-7d79d51f967a%26entityType%3Dcollection%26workspaceId%3D3664098f-4f8b-4edf-874d-ed33e1eea8ed) You can find our postman collection source in our [public repository on github](https://github.com/NHSDigital/communications-manager-api/tree/master/postman). ### Integration testing Our integration test environment: * is for formal integration sandbox-testing * is stateful, so persists updates * includes authorisation via [signed JWT authentication](https://digital.nhs.uk/developer/guides-and-documentation/security-and-authorisation/application-restricted-restful-apis-signed-jwt-authentication) You 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: [![Run in Postman](https://run.pstmn.io/button.svg)](https://god.gw.postman.com/run-collection/28740466-fbe32763-302e-4a0b-b6e9-3a20f1bde923?action=collection%2Ffork&source=rip_markdown&collection-url=entityId%3D28740466-fbe32763-302e-4a0b-b6e9-3a20f1bde923%26entityType%3Dcollection%26workspaceId%3D3664098f-4f8b-4edf-874d-ed33e1eea8ed#?env%5BIntegration%5D=W3sia2V5IjoiYXBpX2tleSIsInZhbHVlIjoiIiwiZW5hYmxlZCI6dHJ1ZSwidHlwZSI6InNlY3JldCIsInNlc3Npb25WYWx1ZSI6IldPekdrM1dFWDBjVU9pbmhsNkdvdVd2N0RXTEhWaUNOIiwic2Vzc2lvbkluZGV4IjowfSx7ImtleSI6InByaXZhdGVfa2V5IiwidmFsdWUiOiIiLCJlbmFibGVkIjp0cnVlLCJ0eXBlIjoic2VjcmV0Iiwic2Vzc2lvblZhbHVlIjoiLS0tLS1CRUdJTiBQUklWQVRFIEtFWS0tLS0tIE1JSUpRZ0lCQURBTkJna3Foa2lHOXcwQkFRRUZBQVNDQ1N3d2dna29BZ0VBQW9JQ0FRQ2lPZWtqZlJYTWt0cDguLi4iLCJzZXNzaW9uSW5kZXgiOjF9LHsia2V5IjoiYXV0aG9yaXphdGlvbl9oZWFkZXJfdmFsdWUiLCJ2YWx1ZSI6IiIsImVuYWJsZWQiOnRydWUsInR5cGUiOiJzZWNyZXQiLCJzZXNzaW9uVmFsdWUiOiJCZWFyZXIgTmxrd2Z0S3lQYWNXVjcza3VBZ1FVR2pEdkZlcCIsInNlc3Npb25JbmRleCI6Mn0seyJrZXkiOiJjb3JyZWxhdGlvbl9pZCIsInZhbHVlIjoiIiwiZW5hYmxlZCI6dHJ1ZSwidHlwZSI6ImRlZmF1bHQiLCJzZXNzaW9uVmFsdWUiOiI1OTMzOGVhOC1iYjQ0LTRhM2EtOTIwYS0xN2ZiMGEzNTVmNTUiLCJzZXNzaW9uSW5kZXgiOjN9LHsia2V5IjoibWltZV90eXBlIiwidmFsdWUiOiJhcHBsaWNhdGlvbi92bmQuYXBpK2pzb24iLCJlbmFibGVkIjp0cnVlLCJ0eXBlIjoiZGVmYXVsdCIsInNlc3Npb25WYWx1ZSI6ImFwcGxpY2F0aW9uL3ZuZC5hcGkranNvbiIsInNlc3Npb25JbmRleCI6NH0seyJrZXkiOiJtZXNzYWdlX2JhdGNoX3JlZmVyZW5jZSIsInZhbHVlIjoiIiwiZW5hYmxlZCI6dHJ1ZSwidHlwZSI6ImRlZmF1bHQiLCJzZXNzaW9uVmFsdWUiOiJmNjI1Yjc4OS04YTZlLTQ1ODEtOGM1Zi03ZWExMWMyNTRiNmYiLCJzZXNzaW9uSW5kZXgiOjV9XQ==) Alternatively you can find our postman collection source in our [public repository on github](https://github.com/NHSDigital/communications-manager-api/tree/master/postman). ## Onboarding You need to get your software approved by us before it can go live with this API. You will also need to undertake the Communications Manager onboarding process which is still being defined. Further details will follow. To understand how our online digital onboarding process works, see [digital onboarding](https://digital.nhs.uk/developer/guides-and-documentation/digital-onboarding). ## Errors We use standard HTTP status codes to show whether an API request succeeded or not. They are usually in the range: * 200 to 299 if it succeeded, including code 202 if it was accepted by an API that needs to wait for further action * 400 to 499 if it failed because of a client error by your application * 500 to 599 if it failed because of an error on our server Errors 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). contact: name: Communications Manager Service 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 paths: /v1/message-batches: post: summary: Send messages description: |- ## Overview Use this endpoint to send a batch of messages to 1 or more NHS patients. ### References You must provide two reference values within the payload to this endpoint: * A message batch reference * A per message reference Both of these references must be a [Universal Unique Identifier (UUID)](https://en.wikipedia.org/wiki/Universally_unique_identifier). The message batch reference (`messageBatchReference`) is unique for you. If you send the same message batch reference multiple times we will automatically deduplicate the requests - actioning only the first payload that has been sent. This value is used to store your reference for this batch of messages. The 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. ### Personalisation You will 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. These are not validated when we store your message batch, but will be validated when we attempt to send the messages according to the routing plan. If there are values missing from this then the messages will fail to send. ### Sandbox When sending this request on sandbox you must use one of the 5 preconfigured routing plan identifiers: * `b838b13c-f98c-4def-93f0-515d4e4f4ee1` * `49e43b98-70cb-47a9-a55e-fe70c9a6f77c` * `b402cd20-b62a-4357-8e02-2952959531c8` * `936e9d45-15de-4a95-bb36-ae163c33ae53` * `9ba00d23-cd6f-4aca-8688-00abc85a7980` On other environments these values will be established as part of your [Communications Manager Service onboarding](#overview--onboarding). Here is an example curl request which creates a message batch using one of these routing plan identifiers: ``` curl -X POST \ --header "Accept: */*" \ --header "Content-type: application/vnd.api+json" \ -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","dateOfBirth": "1932-01-06"},"personalisation": {}}]}}}' \ https://sandbox.api.service.nhs.uk/comms/v1/message-batches ``` 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). Required 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. Mirrored back in a response header. schema: type: string example: 11C46F5F-CDEF-4865-94B2-0EE0EDCC26DA requestBody: description: '' content: application/vnd.api+json: schema: $ref: '#/components/schemas/CreateMessageBatch' application/json: schema: $ref: '#/components/schemas/CreateMessageBatch' 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. The response includes both your `messageBatchReference` and our message batch `id`. You should store this `id` in your database. content: application/vnd.api+json: schema: $ref: '#/components/schemas/MessageBatchResponse' application/json: schema: $ref: '#/components/schemas/MessageBatchResponse' headers: X-Correlation-ID: schema: type: string pattern: 11C46F5F-CDEF-4865-94B2-0EE0EDCC26DA description: 'The X-Correlation-ID from the request header, if supplied, mirrored back.' '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. The following validation errors can occur: | Error code | Title | Description | | ---------- | ----- | ----------- | | `CM_MISSING_VALUE` | Missing property | The property at the specified location is required, but was not present in the request. | | `CM_NULL_VALUE` | Property cannot be null | The property at the specified location is required, but a null value was passed in the request. | | `CM_INVALID_VALUE` | Invalid value | The property at the specified location does not allow this value. | | `CM_INVALID_NHS_NUMBER` | Invalid nhs number | The value provided in this nhsNumber field is not a valid NHS number. | | `CM_DUPLICATE_VALUE` | Duplicate value | The property at the specified location is a duplicate, duplicated values are not allowed. | | `CM_TOO_FEW_ITEMS` | Too few items | The property at the specified location contains too few items. | Within each error is a source object which details the location of the error within your request body. This 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). content: application/vnd.api+json: schema: $ref: '#/components/schemas/UnableToProcessResponse' application/json: schema: $ref: '#/components/schemas/UnableToProcessResponse' headers: X-Correlation-ID: schema: type: string pattern: 11C46F5F-CDEF-4865-94B2-0EE0EDCC26DA description: 'The X-Correlation-ID from the request header, if supplied, mirrored back.' '401': description: |+ Your request was not authorized - you need to send a `Authorization` header with a valid `Bearer` token. See 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). ### Sandbox It is possible to trigger this error in the sandbox by sending the header `Prefer` with a value of `code=401`. Here is an example curl request to trigger a `401`: ``` curl -X GET \ --header "Accept: */*" \ --header "Prefer: code=401" \ https://sandbox.api.service.nhs.uk/comms/ ``` content: application/vnd.api+json: schema: $ref: '#/components/schemas/AccessDeniedResponse' application/json: schema: $ref: '#/components/schemas/AccessDeniedResponse' headers: X-Correlation-ID: schema: type: string pattern: 11C46F5F-CDEF-4865-94B2-0EE0EDCC26DA description: 'The X-Correlation-ID from the request header, if supplied, mirrored back.' '403': description: |+ Your request contained an authentic bearer token in the `Authorization` header but you are not authorized to make the request. This is due the onboarding process not having been completed. Refer to our [onboarding](#overview--onboarding) section for more information. ### Sandbox It is possible to trigger this error in the sandbox by sending the header `Prefer` with a value of `code=403`. Here is an example curl request to trigger a `403`: ``` curl -X GET \ --header "Accept: */*" \ --header "Prefer: code=403" \ https://sandbox.api.service.nhs.uk/comms/ ``` content: application/vnd.api+json: schema: $ref: '#/components/schemas/ForbiddenResponse' application/json: schema: $ref: '#/components/schemas/ForbiddenResponse' headers: X-Correlation-ID: schema: type: string pattern: 11C46F5F-CDEF-4865-94B2-0EE0EDCC26DA description: 'The X-Correlation-ID from the request header, if supplied, mirrored back.' '404': description: |+ The routing plan identifier passed in the body has not been found. When 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. ### Sandbox On the sandbox environment there are 5 valid routing plan identifiers that can be used by anybody calling the API. These are: * `b838b13c-f98c-4def-93f0-515d4e4f4ee1` * `49e43b98-70cb-47a9-a55e-fe70c9a6f77c` * `b402cd20-b62a-4357-8e02-2952959531c8` * `936e9d45-15de-4a95-bb36-ae163c33ae53` * `9ba00d23-cd6f-4aca-8688-00abc85a7980` If you use a routing plan id that is not in this list then a `404 Not Found` error response will be triggered. On other environments these values will be established as part of your [Communications Manager Service onboarding](#overview--onboarding). Here is an example curl request to trigger a `404`: ``` curl -X POST \ --header "Accept: */*" \ --header "Content-type: application/vnd.api+json" \ -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","dateOfBirth": "1932-01-06"},"personalisation": {}}]}}}' \ https://sandbox.api.service.nhs.uk/comms/v1/message-batches ``` content: application/vnd.api+json: schema: $ref: '#/components/schemas/RoutingPlanNotFoundError' application/json: schema: $ref: '#/components/schemas/RoutingPlanNotFoundError' headers: X-Correlation-ID: schema: type: string pattern: 11C46F5F-CDEF-4865-94B2-0EE0EDCC26DA description: 'The X-Correlation-ID from the request header, if supplied, mirrored back.' '406': description: |+ The request did not contain a valid `Accept` header value. Valid values are: * `*/*` * `application/json` * `application/vnd.api+json` Where no `Accept` header is present, this will default to `application/vnd.api+json` content: application/vnd.api+json: schema: $ref: '#/components/schemas/NotAcceptable' headers: X-Correlation-ID: schema: type: string pattern: 11C46F5F-CDEF-4865-94B2-0EE0EDCC26DA description: 'The X-Correlation-ID from the request header, if supplied, mirrored back.' '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. There may also be an issue within our backend where a `408` has been bubbled up and exposed. This could be indicative of an ongoing infrastructure issue that is out of our (or your) control. ### Sandbox It is possible to simulate this error response by sending a request with a header of `Prefer` set to the value `code=408`. Here is an example curl request to simulate this response: ``` curl -X GET --header "Prefer: code=408" https://sandbox.api.service.nhs.uk/comms/ ``` To simulate a backend `408` exception bubbling upwards you can send this request: ``` curl -X GET https://sandbox.api.service.nhs.uk/comms/_timeout_408 ``` content: application/vnd.api+json: schema: $ref: '#/components/schemas/RequestTimeoutResponse' application/json: schema: $ref: '#/components/schemas/RequestTimeoutResponse' headers: X-Correlation-ID: schema: type: string pattern: 11C46F5F-CDEF-4865-94B2-0EE0EDCC26DA description: 'The X-Correlation-ID from the request header, if supplied, mirrored back.' '415': description: |+ The `Content-Type` of the request is not supported. This endpoint supports: * `application/vnd.api+json` * `application/json` content: application/vnd.api+json: schema: $ref: '#/components/schemas/UnsupportedMediaResponse' application/json: schema: $ref: '#/components/schemas/UnsupportedMediaResponse' headers: X-Correlation-ID: schema: type: string pattern: 11C46F5F-CDEF-4865-94B2-0EE0EDCC26DA description: 'The X-Correlation-ID from the request header, if supplied, mirrored back.' '429': description: |+ You have made too many requests too quickly, you must send requests at a slower rate. If 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. ### Sandbox It is possible to trigger this on the sandbox by using the `Prefer` header with a value of `code=429`. Here is an example curl request to trigger a `429`: ``` curl -X GET --header "Prefer: code=429" https://sandbox.api.service.nhs.uk/comms/ ``` content: application/vnd.api+json: schema: $ref: '#/components/schemas/TooManyRequestsResponse' application/json: schema: $ref: '#/components/schemas/TooManyRequestsResponse' 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: 'The X-Correlation-ID from the request header, if supplied, mirrored back.' '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. The following errors can occur: | Error code | Title | Description | | ---------- | ----- | ----------- | | `CM_MISSING_ROUTING_PLAN_TEMPLATE` | Templates missing | The templates required to use the routing plan were not found. | | `CM_ROUTING_PLAN_DUPLICATE_TEMPLATES` | Duplicate templates | The routing plan specified contains duplicate templates. | | `CM_INTERNAL_SERVER_ERROR` | Error processing request | There was an internal error whilst processing this request. | Within each error is a source object which details the location of the error within your request body. Certain errors may include an extra set of metadata to assist you with resolving the problem. This 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). ### Sandbox It is possible to simulate these errors by sending requests with specific routing plan identifiers. To 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: ``` curl -X POST \ --header "Accept: */*" \ --header "Content-type: application/vnd.api+json" \ -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","dateOfBirth": "1932-01-06"},"personalisation": {}}]}}}' \ https://sandbox.api.service.nhs.uk/comms/v1/message-batches ``` To 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: ``` curl -X POST \ --header "Accept: */*" \ --header "Content-type: application/vnd.api+json" \ -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","dateOfBirth": "1932-01-06"},"personalisation": {}}]}}}' \ https://sandbox.api.service.nhs.uk/comms/v1/message-batches ``` It is possible to trigger the `CM_INTERNAL_SERVER_ERROR` on the sandbox by using the `Prefer` header with a value of `code=500`. Here is an example curl request to trigger a `500`: ``` curl -X GET --header "Prefer: code=500" https://sandbox.api.service.nhs.uk/comms/ ``` content: application/vnd.api+json: schema: $ref: '#/components/schemas/InternalServerError' application/json: schema: $ref: '#/components/schemas/InternalServerError' headers: X-Correlation-ID: schema: type: string pattern: 11C46F5F-CDEF-4865-94B2-0EE0EDCC26DA description: 'The X-Correlation-ID from the request header, if supplied, mirrored back.' '503': description: |+ The service is currently not accepting requests, This error can occur if any part of the system has gone offline. ### Sandbox It is possible to simulate this error response by sending a request with a header of `Prefer` set to the value `code=503`. Here is an example curl request to simulate this response: ``` curl -X GET --header "Prefer: code=503" https://sandbox.api.service.nhs.uk/comms/ ``` content: application/vnd.api+json: schema: $ref: '#/components/schemas/ServiceUnavailableResponse' application/json: schema: $ref: '#/components/schemas/ServiceUnavailableResponse' 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: 'The X-Correlation-ID from the request header, if supplied, mirrored back.' '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). This error can occur if there is an issue with a dependent service and so may be bubbled up from a 3rd party HTTP call. ### Sandbox It is possible to simulate this error response by sending a request with a header of `Prefer` set to the value `code=504`. Here is an example curl request to simulate this response: ``` curl -X GET --header "Prefer: code=504" https://sandbox.api.service.nhs.uk/comms/ ``` To simulate a backend `504` exception bubbling upwards you can send this request: ``` curl -X GET https://sandbox.api.service.nhs.uk/comms/_timeout_504 ``` content: application/vnd.api+json: schema: $ref: '#/components/schemas/ServiceTimeoutResponse' application/json: schema: $ref: '#/components/schemas/ServiceTimeoutResponse' headers: X-Correlation-ID: schema: type: string pattern: 11C46F5F-CDEF-4865-94B2-0EE0EDCC26DA description: 'The X-Correlation-ID from the request header, if supplied, mirrored back.' components: schemas: CreateMessageBatch: $ref: schemas/CreateMessageBatch.yaml Message: $ref: schemas/Message.yaml Recipient: $ref: schemas/Recipient.yaml MessageBatchResponse: $ref: schemas/MessageBatchResponse.yaml Type_KSUID: $ref: schemas/TypeKSUID.yaml Type_ErrorIdentifier: $ref: schemas/TypeErrorIdentifier.yaml UnableToProcessResponse: $ref: schemas/UnableToProcessResponse.yaml InternalServerError: $ref: schemas/InternalServerError.yaml AccessDeniedResponse: $ref: schemas/AccessDeniedResponse.yaml ForbiddenResponse: $ref: schemas/ForbiddenResponse.yaml RoutingPlanNotFoundError: $ref: schemas/RoutingPlanNotFoundError.yaml NotAcceptable: $ref: schemas/NotAcceptable.yaml RequestTimeoutResponse: $ref: schemas/RequestTimeoutResponse.yaml UnsupportedMediaResponse: $ref: schemas/UnsupportedMediaResponse.yaml TooManyRequestsResponse: $ref: schemas/TooManyRequestsResponse.yaml ServiceUnavailableResponse: $ref: schemas/ServiceUnavailableResponse.yaml ServiceTimeoutResponse: $ref: schemas/ServiceTimeoutResponse.yaml Links_Error: $ref: schemas/LinksError.yaml