--- title: "Send a batch of messages" method: POST path: "/v1/message-batches" --- # Send a batch of messages `POST /v1/message-batches` ## 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 The message batch reference (`messageBatchReference`) is unique for you. 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 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. Messages 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. ### Sandbox When sending this request on sandbox you must use one of the 6 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` - `00000000-0000-0000-0000-000000000001` On other environments these values will be established as part of your [NHS Notify 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"},"originator": {"odsCode":"X123"},"personalisation": {},"answerOptions": {"NHSAPP":[{"code":"Yes"},{"code":"No"}]}}]}}}' \ https://sandbox.api.service.nhs.uk/comms/v1/message-batches ``` ## Parameters - `#/paths/~1v1~1messages/post/parameters/0` — unresolved $ref - `#/paths/~1v1~1messages/post/parameters/1` — unresolved $ref ## Request body - object - `data` object, required - `type` 'MessageBatch', required - `attributes` object, required — MessageBatch attributes. - `routingPlanId` string, uuid, required — 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). There are also some global routingPlanIds available, please see the [Free-text communications documentation](#section/Free-text-communications). If you send through an invalid routing plan id you will receive a 404 response. - `messageBatchReference` string, required — 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. - `messages` object[], required - `messageReference` string, required — 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. - `billingReference` BillingReference — unresolved $ref - `recipient` Recipient, required — unresolved $ref - `originator` Originator — unresolved $ref - `personalisation` object — The personalisation keys and values for this message. These are linked to the routingPlanId provided and are agreed upon during [onboarding](#overview--onboarding). - `answerOptions` AnswerOptions — unresolved $ref ## Response `201` 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 an array with your `messageReference` and our message `id` for each message in your request. You 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. - object - `data` object - `type` Type, required — unresolved $ref - `id` Schema, required — unresolved $ref - `attributes` object, required - `messageBatchReference` string, required — Your unique message batch reference, provided within the payload to create the batch of messages. - `routingPlan` RoutingPlan, required — unresolved $ref - `messages` object[], required - `messageReference` MessageReference, required — unresolved $ref - `id` Schema, required — unresolved $ref ## Other responses - `400` — 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. | | `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. | | `CM_CANNOT_SET_ODS_CODE` | Cannot set ODS code | Your account is not permitted to set originator ODS codes. | | `CM_CANNOT_SET_CONTACT_DETAILS` | Cannot set contact details | Your account is not allowed to provide alternative contact details. | 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). ### Sandbox It is possible to trigger some of the errors in the sandbox by sending the header `Authorization` with certain values. Here is an example curl request to trigger a `CM_CANNOT_SET_ODS_CODE`: ``` curl -X POST \ --header "Accept: */*" \ --header "Content-type: application/vnd.api+json" \ --header "Authorization: noOdsChange" \ -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":{}}]}}}' \ https://sandbox.api.service.nhs.uk/comms/v1/message-batches ``` Here is an example curl request to trigger a `CM_CANNOT_SET_CONTACT_DETAILS`: ``` curl -X POST \ --header "Accept: */*" \ --header "Content-type: application/vnd.api+json" \ --header "Authorization: notAllowedContactDetailOverride" \ -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":{}}]}}}' \ https://sandbox.api.service.nhs.uk/comms/v1/message-batches ``` - `401` — unresolved $ref - `403` — unresolved $ref - `404` — 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 [NHS Notify 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"},"originator": {"odsCode":"X123"},"personalisation": {}}]}}}' \ https://sandbox.api.service.nhs.uk/comms/v1/message-batches ``` - `405` — unresolved $ref - `406` — unresolved $ref - `408` — unresolved $ref - `413` — 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. - `415` — unresolved $ref - `422` — 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. ### Sandbox It is possible to trigger this on the sandbox by using the `Prefer` header with a value of `code=422_batch`. Here is an example curl request to trigger a `422`: ``` curl -X GET --header "Prefer: code=422_batch" https://sandbox.api.service.nhs.uk/comms/ ``` - `425` — unresolved $ref - `429` — unresolved $ref - `500` — 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"},"originator": {"odsCode":"X123"},"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"},"originator": {"odsCode":"X123"},"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/ ``` - `503` — unresolved $ref - `504` — unresolved $ref --- [API](https://skmtc.dev/nhs/apis/communications-manager-api.md) · [All operations](https://skmtc.dev/nhs/apis/communications-manager-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/nhs/communications-manager-api/revisions/286b22343680/schema)