Sign in

v1

latestOpenAPI 3.0.02026-07-144080.8 KB
communication

Get a daily receipt report

Overview

Use this endpoint to get a daily report of receipts relating to in-app messages and push notifications that you have sent to NHS App users.

This report will include receipts detailing the outcome of an attempt to send each communication. For in-app messages, a receipt will also be included in this report if the recipient reads the message.

The following five types of receipt may be included in this response:

  • Rejected – a request to send a communication was rejected. For example, this could happen if the NHS number of the intended recipient does not correspond to an NHS App user.
  • Delivered – an in-app message has been successfully added to a user’s inbox.
  • NotificationAttempted - a push notification request has been accepted by Apple Push Notification Service or Firebase Cloud Messaging. This doesn't confirm whether the user ends up receiving the push notification or not, just that the request coming from the NHS has been accepted (as opposed to rejected, in which case the supplier will receive the Unnotified receipt).
  • Notified – a push notification has been displayed by at least one native device. For iOS, if the user has enabled a notifications schedule, then this receipt will only be sent once the scheduled time has been reached.
  • Unnotified – it has been determined that a push notification has not been successfully relayed to any native devices.
  • Read – a user has read an in-app message for the first time.

Message Overview

A diagram of a finite state machine showing the transition between delivery states based on events occurring throughout the delivery process, such as successfully adding a message to a citizen’s inbox and displaying a notification on their mobile device.

In addition to this daily report endpoint, we also offer the ability for onboarded partners to receive these receipts in realtime by having us push individual Task resources to an endpoint that you make available to us for this purpose. We call this feature "real-time receipts". We have created an OpenAPI specification detailing the behaviour of the endpoint that you should create to subscribe to realtime receipts.

Pagination

To 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 Link header or Link array in the response body should be inspected to determine whether any additional pages of results exist. If so, these can be retrieved by making additional request(s) with the optional page parameter specified.

get/communication/report/receipts/FHIR/R4/Task

Query parameters

daystring date required

The day for which to retrieve a receipt report.

pageinteger

The ordinal number of the page of results to be retrieved. If omitted, the first page of results will be returned. Use the Link header in the response to determine whether any further pages of results exist.

Response

Information successfully returned.

resourceType'Bundle' required
type'searchset' required

Example response

{
  "resourceType": "Bundle",
  "type": "searchset",
  "link": [
    {
      "relation": "self",
      "url": "https://api.service.nhs.uk/nhs-app/communication/report/events/FHIR/R4/Task?day=2022-08-19&page=1"
    }
  ],
  "entry": [
    {
      "fullUrl": "https://api.service.nhs.uk/nhs-app/communication/report/events/FHIR/R4/Task/b2ac2ae7-1a24-4e90-8f3f-9a62c6ebb4e7",
      "resource": {
        "id": "b2ac2ae7-1a24-4e90-8f3f-9a62c6ebb4e7",
        "resourceType": "Task",
        "intent": "order",
        "identifier": [
          {
            "system": "https://fhir.nhs.uk/Id/nhs-app-communication-id",
            "value": "882cc757-5096-4565-9779-af25a751a65f"
          }
        ],
        "status": "completed",
        "statusReason": "NHS number not found",
        "code": {
          "coding": [
            {
              "system": "https://fhir.nhs.uk/CodeSystem/NHSApp-Communication-Status",
              "code": "Delivered"
            }
          ]
        },
        "authoredOn": "2022-08-19T09:15:12Z",
        "lastModified": "2022-08-19T09:15:56Z"
      }
    }
  ]
}