openapi: 3.0.0 info: version: '1.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 ## 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 an integration or 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. ### 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) | ## 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. ## 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 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": "1234567890","dateOfBirth": "1982-03-17"},"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_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": "1234567890","dateOfBirth": "1982-03-17"},"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` content: application/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`. 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": "1234567890","dateOfBirth": "1982-03-17"},"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": "1234567890","dateOfBirth": "1982-03-17"},"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.' security: [] 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 components: schemas: CreateMessageBatch: type: object title: Create message batch properties: data: type: object properties: type: $ref: '#/components/schemas/Enum_Type_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). If you send through an invalid routing plan 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. This 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. format: uuid example: da0b1495-c7cb-468c-9d81-07dee089d728 messages: type: array items: $ref: '#/components/schemas/Message' required: - routingPlanId - messageBatchReference - messages required: - type - attributes required: - data Enum_Type_MessageBatch: type: string enum: - MessageBatch title: Type_MessageBatch example: MessageBatch Message: type: object title: Message 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. format: uuid example: 703b8008-545d-4a04-bb90-1f2946ce1575 recipient: $ref: '#/components/schemas/Recipient' 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 Recipient: type: object title: Recipient properties: nhsNumber: type: string pattern: '^\d{10}$' minLength: 10 maxLength: 10 example: '1234567890' description: The [NHS number](https://digital.nhs.uk/services/nhs-number) of the recipient. 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). dateOfBirth: type: string description: 'Date of birth in ISO-8601 format: YYYY-MM-DD.' format: date example: '1982-03-17' required: - nhsNumber MessageBatchResponse: type: object title: Message batch response additionalProperties: false properties: data: type: object additionalProperties: false properties: type: $ref: '#/components/schemas/Enum_Type_MessageBatch' id: $ref: '#/components/schemas/Type_KSUID' description: Identifier for this MessageBatch. You should store this identifier for later lookups. attributes: type: object additionalProperties: false properties: messageBatchReference: type: string description: Your unique message batch reference, provided within the payload to create the batch of messages. format: uuid example: da0b1495-c7cb-468c-9d81-07dee089d728 Type_KSUID: type: string title: Type_KSUID pattern: '^[a-zA-Z0-9]{27}$' minLength: 27 maxLength: 27 example: 0ujsszwN8NRY24YaXiTIE2VWDTS UnableToProcessResponse: type: object title: Request not processable additionalProperties: false properties: errors: type: array minItems: 1 uniqueItems: true items: type: object properties: id: $ref: '#/components/schemas/Enum_Error_InvalidValue' links: $ref: '#/components/schemas/Links_Error' status: type: string enum: - '400' example: '400' title: type: string enum: - Missing property - Property cannot be null - Invalid value - Duplicate value - Too few items example: Missing property detail: type: string enum: - 'The property at the specified location is required, but was not present in the request.' - 'The property at the specified location is required, but a null value was passed in the request.' - The property at the specified location does not allow this value. - 'The property at the specified location is a duplicate, duplicated values are not allowed.' - The property at the specified location contains too few items. example: 'The property at the specified location is required, but was not present in the request.' source: type: object additionalProperties: false properties: pointer: type: string enum: - /data/type - /data/attributes - /data/attributes/messageBatchReference - /data/attributes/routingPlanId - /data/attributes/messages - /data/attributes/messages/0/recipient/nhsNumber - /data/attributes/messages/0/recipient/dateOfBirth - /data/attributes/messages/0/messageReference example: /data/attributes/routingPlanId Enum_Error_InvalidValue: type: string enum: - CM_MISSING_VALUE - CM_NULL_VALUE - CM_INVALID_VALUE - CM_DUPLICATE_VALUE - CM_TOO_FEW_ITEMS example: CM_MISSING_VALUE title: Enum_Error_InvalidValue InternalServerError: type: object title: Internal server error additionalProperties: false properties: errors: type: array minItems: 1 uniqueItems: true items: type: object properties: id: $ref: '#/components/schemas/Enum_Error_InternalServerError' links: $ref: '#/components/schemas/Links_Error' status: type: string enum: - '500' example: '500' title: type: string enum: - Templates missing - Duplicate templates 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.' 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 Enum_Error_InternalServerError: type: string enum: - CM_ROUTING_PLAN_DUPLICATE_TEMPLATES - CM_MISSING_ROUTING_PLAN_TEMPLATE example: CM_MISSING_ROUTING_PLAN_TEMPLATE title: Enum_Error_InternalServerError AccessDeniedResponse: type: object title: Access Denied additionalProperties: false properties: errors: type: array minItems: 1 maxItems: 1 uniqueItems: true items: type: object properties: id: $ref: '#/components/schemas/Enum_Error_AccessDenied' links: $ref: '#/components/schemas/Links_Error' 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 Enum_Error_AccessDenied: type: string enum: - CM_DENIED example: CM_DENIED title: Enum_Error_AccessDenied ForbiddenResponse: type: object title: Forbidden additionalProperties: false properties: errors: type: array minItems: 1 maxItems: 1 uniqueItems: true items: type: object properties: id: $ref: '#/components/schemas/Enum_Error_Forbidden' links: $ref: '#/components/schemas/Links_Error' status: type: string enum: - '403' example: '403' title: type: string enum: - Forbidden example: Forbidden detail: type: string enum: - Client not recognised or not yet onboarded. example: Client not recognised or not yet onboarded. source: type: object additionalProperties: false properties: header: type: string enum: - Authorization example: Authorization Enum_Error_Forbidden: type: string enum: - CM_FORBIDDEN example: CM_FORBIDDEN title: Enum_Error_Forbidden RoutingPlanNotFoundError: type: object title: No such routing plan additionalProperties: false properties: errors: type: array minItems: 1 maxItems: 1 uniqueItems: true items: type: object properties: id: $ref: '#/components/schemas/Enum_Error_NoSuchRoutingPlan' links: $ref: '#/components/schemas/Links_Error' 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 Enum_Error_NoSuchRoutingPlan: type: string enum: - CM_NO_SUCH_ROUTING_PLAN example: CM_NO_SUCH_ROUTING_PLAN title: Enum_Error_NoSuchRoutingPlan NotAcceptable: type: object title: Not Acceptable additionalProperties: false properties: errors: type: array minItems: 1 maxItems: 1 uniqueItems: true items: type: object properties: id: $ref: '#/components/schemas/Enum_Error_NotAcceptable' links: $ref: '#/components/schemas/Links_Error' 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 Enum_Error_NotAcceptable: type: string enum: - CM_NOT_ACCEPTABLE title: Enum_Error_NotAcceptable example: CM_NOT_ACCEPTABLE RequestTimeoutResponse: type: object title: Request timeout additionalProperties: false properties: errors: type: array minItems: 1 maxItems: 1 uniqueItems: true items: type: object properties: id: $ref: '#/components/schemas/Enum_Error_Timeout' links: $ref: '#/components/schemas/Links_Error' 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. Enum_Error_Timeout: type: string enum: - CM_TIMEOUT title: Enum_Error_Timeout example: CM_TIMEOUT UnsupportedMediaResponse: type: object title: Unsupported Media additionalProperties: false properties: errors: type: array minItems: 1 maxItems: 1 uniqueItems: true items: type: object properties: id: $ref: '#/components/schemas/Enum_Error_UnsupportedMedia' links: $ref: '#/components/schemas/Links_Error' 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 Enum_Error_UnsupportedMedia: type: string enum: - CM_UNSUPPORTED_MEDIA title: Enum_Error_UnsupportedMedia example: CM_UNSUPPORTED_MEDIA TooManyRequestsResponse: type: object title: Too many requests additionalProperties: false properties: errors: type: array minItems: 1 maxItems: 1 uniqueItems: true items: type: object properties: id: $ref: '#/components/schemas/Enum_Error_Quota' links: $ref: '#/components/schemas/Links_Error' 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. Enum_Error_Quota: type: string title: Enum_Error_Quota enum: - CM_QUOTA example: CM_QUOTA ServiceUnavailableResponse: type: object title: Service unavailable additionalProperties: false properties: errors: type: array minItems: 1 maxItems: 1 uniqueItems: true items: type: object properties: id: $ref: '#/components/schemas/Enum_Error_ServiceUnavailable' links: $ref: '#/components/schemas/Links_Error' 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. Enum_Error_ServiceUnavailable: type: string title: Enum_Error_ServiceUnavailable enum: - CM_SERVICE_UNAVAILABLE example: CM_SERVICE_UNAVAILABLE ServiceTimeoutResponse: type: object title: Service timeout additionalProperties: false properties: errors: type: array minItems: 1 maxItems: 1 uniqueItems: true items: type: object properties: id: $ref: '#/components/schemas/Enum_Error_Timeout' links: $ref: '#/components/schemas/Links_Error' 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. Links_Error: type: object additionalProperties: false properties: about: type: string enum: - 'https://digital.nhs.uk/developer/api-catalogue/communications-manager' format: uri example: 'https://digital.nhs.uk/developer/api-catalogue/communications-manager' minProperties: 1