NHS App API

---

Endpoints: Communication

Send an in-app message

Overview

Use this endpoint to send an in-app message followed by an associated native Apple or Android push notification to a single NHS App user.

Push notifications will not be sent to users between the hours of 10pm and 6am UK time. If a valid request to send an in-app message with an associated push notification is processed between these hours, the in-app message will be delivered immediately, and the push notification will be scheduled for delivery at 6am.

Recipients are specified by NHS number. A single request to this endpoint can send a message and push notification to a single NHS App user. In-app messages and push notifications will only be sent to users who have had their identity verified to 'high' (P9) level.

If a recipient is an active NHS App user but has not registered a device to receive native push notifications, they will still receive the in-app message.

This endpoint allows you to specify the content that will appear in the in-app message. It does not allow you to specify the content that will appear in the associated push notification. By default, the content of the associated push notification will read "NHS App. You have a new message." To discuss changing this standard push notification content for your application, contact the NHS App team.

When a recipient taps the native notification, the NHS App will open on the in-app messaging inbox page.

We support a subset of Markdown for describing the body text of in-app messages. For details of the subset see the 'payload' property of the schema. The length of each in-app message is limited to 5000 characters, including any markdown characters and embedded hyperlinks.

The body of requests made to this endpoint are instances of HL7 FHIR R4 CommunicationRequest resources. This schema documentation describes which fields on that resource we require and support. The API is tolerant of (but will silently ignore) any additionally supplied optional fields. For example, we do not currently honour the doNotPerform or priority fields.

The outcome of communication requests can be determined using the daily receipt report endpoint. You may also create an endpoint into which NHS App can post the outcome of individual communication requests in realtime — we call this feature "realtime receipts". We have created (https://github.com/NHSDigital/nhs-app-api/tree/master/specifications-callbacks/realtime-receipts)[an Open API specification] detailing the behaviour of the endpoint that you should create to subscribe to realtime receipts.

Request

Headers

Body

Content type: application/json

Examples

Sending an in-app message

{
  "resourceType" : "CommunicationRequest",
  "identifier" : [ {
    "system" : "https://fhir.nhs.uk/NHSApp/campaign-id",
    "value" : "optional campaign id"
  }, {
    "system" : "https://fhir.nhs.uk/NHSApp/request-id",
    "value" : "optional request reference"
  } ],
  "status" : "active",
  "payload" : [ {
    "contentString" : "You have a new appointment, please confirm you can attend. Open the Onboarded Third Party appointment [here](https://www.nhsapp.service.nhs.uk/appointments/hospital-appointments)"
  } ],
  "recipient" : [ {
    "type" : "Patient",
    "identifier" : {
      "system" : "https://fhir.nhs.uk/Id/nhs-number",
      "value" : "9903002157"
    }
  } ],
  "requester" : {
    "type" : "Organization",
    "identifier" : {
      "system" : "https://fhir.nhs.uk/Id/ods-organization-code",
      "value" : "B82041"
    }
  }
}

Sending an in-app message with keyword reply

{
  "resourceType" : "CommunicationRequest",
  "identifier" : [ {
    "system" : "https://fhir.nhs.uk/NHSApp/campaign-id",
    "value" : "optional campaign id"
  }, {
    "system" : "https://fhir.nhs.uk/NHSApp/request-id",
    "value" : "optional request reference"
  } ],
  "status" : "active",
  "payload" : [ {
    "contentString" : " Hello, we would like to ask a few questions about smoking. If you smoke, select SMOKE.  If you're an ex-smoker, select EX. If you have never smoked, select NEVER."
  } ],
  "contained" : [ {
    "resourceType" : "Questionnaire",
    "id" : "answeroptions",
    "status" : "active",
    "item" : [ {
      "linkId" : "1",
      "type" : "choice",
      "answerOption" : [ {
        "valueCoding" : {
          "code" : "SMOKE"
        }
      }, {
        "valueCoding" : {
          "code" : "EX"
        }
      }, {
        "valueCoding" : {
          "code" : "NEVER"
        }
      } ]
    } ]
  } ],
  "extension" : [ {
    "url" : "https://fhir.nhs.uk/NHSApp/answers",
    "valueReference" : {
      "reference" : "#answeroptions"
    }
  } ],
  "recipient" : [ {
    "type" : "Patient",
    "identifier" : {
      "system" : "https://fhir.nhs.uk/Id/nhs-number",
      "value" : "9692113841"
    }
  } ],
  "requester" : {
    "type" : "Organization",
    "identifier" : {
      "system" : "https://fhir.nhs.uk/Id/ods-organization-code",
      "value" : "B82041"
    }
  }
}

Sending an in-app message with free text replies

{
  "resourceType" : "CommunicationRequest",
  "identifier" : [ {
    "system" : "https://fhir.nhs.uk/NHSApp/campaign-id",
    "value" : "Optional Campaign ID"
  }, {
    "system" : "https://fhir.nhs.uk/NHSApp/request-id",
    "value" : "Optional Request Reference"
  } ],
  "status" : "active",
  "payload" : [ {
    "contentString" : " Hello, we would like you to update us with your medical condition."
  } ],
  "contained" : [ {
    "resourceType" : "Questionnaire",
    "id" : "answer",
    "status" : "active",
    "item" : [ {
      "linkId" : "1",
      "type" : "text"
    } ]
  } ],
  "extension" : [ {
    "url" : "https://fhir.nhs.uk/NHSApp/answers",
    "valueReference" : {
      "reference" : "#answer"
    }
  } ],
  "recipient" : [ {
    "type" : "Patient",
    "identifier" : {
      "system" : "https://fhir.nhs.uk/Id/nhs-number",
      "value" : "9692113841"
    }
  } ],
  "requester" : {
    "type" : "Organization",
    "identifier" : {
      "system" : "https://fhir.nhs.uk/Id/ods-organization-code",
      "value" : "B82041"
    }
  }
}

Response

HTTP status: 201

Request successfully received by the server and queued for sending to recipient.

Headers

Body

Content type: application/fhir+json

Examples

In app message response without keyword reply

{
  "resourceType" : "CommunicationRequest",
  "identifier" : [ {
    "system" : "https://fhir.nhs.uk/Id/nhs-app-communication-id",
    "value" : "8f7ec136-66eb-4a9e-97ca-5c7a53d2710c"
  }, {
    "system" : "https://fhir.nhs.uk/NHSApp/campaign-id",
    "value" : "optional campaign id"
  }, {
    "system" : "https://fhir.nhs.uk/NHSApp/request-id",
    "value" : "optional request reference"
  } ],
  "status" : "active",
  "payload" : [ {
    "contentString" : "You have a new appointment, please confirm you can attend. Open the Onboarded Third Party appointment [here](https://www.nhsapp.service.nhs.uk/appointments/hospital-appointments)"
  } ],
  "recipient" : [ {
    "identifier" : {
      "system" : "https://fhir.nhs.uk/Id/nhs-number",
      "value" : "9903002157"
    }
  } ],
  "requester" : {
    "type" : "Organization",
    "identifier" : {
      "system" : "https://fhir.nhs.uk/Id/ods-organization-code",
      "value" : "B82041"
    }
  }
}

In app message response with keyword reply

{
  "resourceType" : "CommunicationRequest",
  "identifier" : [ {
    "system" : "https://fhir.nhs.uk/Id/nhs-app-communication-id",
    "value" : "8f7ec136-66eb-4a9e-97ca-5c7a53d2710c"
  }, {
    "system" : "https://fhir.nhs.uk/NHSApp/campaign-id",
    "value" : "optional campaign id"
  }, {
    "system" : "https://fhir.nhs.uk/NHSApp/request-id",
    "value" : "optional request reference"
  } ],
  "status" : "active",
  "payload" : [ {
    "contentString" : "Dear, we would like to ask a few questions about smoking. If you smoke, select SMOKE.  If you're an ex-smoker, select EX. If you have never smoked, select NEVER."
  } ],
  "contained" : [ {
    "resourceType" : "Questionnaire",
    "id" : "answeroptions",
    "status" : "active",
    "item" : [ {
      "linkId" : "1",
      "type" : "choice",
      "answerOption" : [ {
        "valueCoding" : {
          "code" : "SMOKE"
        }
      }, {
        "valueCoding" : {
          "code" : "EX"
        }
      }, {
        "valueCoding" : {
          "code" : "NEVER"
        }
      } ]
    } ]
  } ],
  "extension" : [ {
    "url" : "https://fhir.nhs.uk/NHSApp/answers",
    "valueReference" : {
      "reference" : "#answeroptions"
    }
  } ],
  "recipient" : [ {
    "identifier" : {
      "system" : "https://fhir.nhs.uk/Id/nhs-number",
      "value" : "9903002157"
    }
  } ],
  "requester" : {
    "type" : "Organization",
    "identifier" : {
      "system" : "https://fhir.nhs.uk/Id/ods-organization-code",
      "value" : "B82041"
    }
  }
}

In app message response with free text reply

{
  "resourceType" : "CommunicationRequest",
  "identifier" : [ {
    "system" : "https://fhir.nhs.uk/Id/nhs-app-communication-id",
    "value" : "8f7ec136-66eb-4a9e-97ca-5c7a53d2710c"
  }, {
    "system" : "https://fhir.nhs.uk/NHSApp/campaign-id",
    "value" : "Optional Campaign ID"
  }, {
    "system" : "https://fhir.nhs.uk/NHSApp/request-id",
    "value" : "Optional Request Reference"
  } ],
  "status" : "active",
  "payload" : [ {
    "contentString" : " Hello, we would like you to update us with your medical condition."
  } ],
  "contained" : [ {
    "resourceType" : "Questionnaire",
    "id" : "answer",
    "status" : "active",
    "item" : [ {
      "linkId" : "1",
      "type" : "text"
    } ]
  } ],
  "extension" : [ {
    "url" : "https://fhir.nhs.uk/NHSApp/answers",
    "valueReference" : {
      "reference" : "#answer"
    }
  } ],
  "recipient" : [ {
    "type" : "Patient",
    "identifier" : {
      "system" : "https://fhir.nhs.uk/Id/nhs-number",
      "value" : "9692113841"
    }
  } ],
  "requester" : {
    "type" : "Organization",
    "identifier" : {
      "system" : "https://fhir.nhs.uk/Id/ods-organization-code",
      "value" : "B82041"
    }
  }
}

HTTP status: 400

There is an error in your request.

Headers

Body

Content type: application/fhir+json

Examples

Invalid resource type

{
  "resourceType" : "OperationOutcome",
  "issue" : [ {
    "severity" : "error",
    "code" : "invalid",
    "diagnostics" : "type (at Cannot locate type information for type 'communicationrequest')"
  } ]
}

Payload body text exceeds maximum length

{
  "resourceType" : "OperationOutcome",
  "issue" : [ {
    "severity" : "error",
    "code" : "invalid",
    "diagnostics" : "Exceeds maximum length",
    "expression" : [ "payload[0].contentString" ]
  } ]
}

No recipient has been specified

{
  "resourceType" : "OperationOutcome",
  "issue" : [ {
    "severity" : "error",
    "code" : "invalid",
    "diagnostics" : "Not specified",
    "expression" : [ "recipient" ]
  } ]
}

A recipient has an invalid NHS number

{
  "resourceType" : "OperationOutcome",
  "issue" : [ {
    "severity" : "error",
    "code" : "invalid",
    "diagnostics" : "NHS Number is invalid",
    "expression" : [ "recipient[0].identifier.value" ]
  } ]
}

Too many recipients have been specified

{
  "resourceType" : "OperationOutcome",
  "issue" : [ {
    "severity" : "error",
    "code" : "invalid",
    "diagnostics" : "Exceeds maximum length",
    "expression" : [ "recipient" ]
  } ]
}

Multiple issues - no recipient has been specified and campaign ID exceeds maximum length

{
  "resourceType" : "OperationOutcome",
  "issue" : [ {
    "severity" : "error",
    "code" : "invalid",
    "diagnostics" : "Multiple Campaign IDs specified",
    "expression" : [ "identifier" ]
  }, {
    "severity" : "error",
    "code" : "invalid",
    "diagnostics" : "Exceeds maximum length",
    "expression" : [ "identifier[2].value" ]
  }, {
    "severity" : "error",
    "code" : "invalid",
    "diagnostics" : "Not specified",
    "expression" : [ "recipient" ]
  } ]
}

The requester has an invalid identifier

{
  "resourceType" : "OperationOutcome",
  "issue" : [ {
    "severity" : "error",
    "code" : "invalid",
    "diagnostics" : "Identifier system is invalid",
    "expression" : [ "requester.identifier.system" ]
  } ]
}

The contained resource type of keyword reply is invalid

{
  "resourceType" : "OperationOutcome",
  "issue" : [ {
    "severity" : "error",
    "code" : "invalid",
    "diagnostics" : "contained should contain one resource of type Questionnaire",
    "expression" : [ "contained[0].type" ]
  } ]
}

The contained item type of keyword or free text reply is invalid

{
  "resourceType" : "OperationOutcome",
  "issue" : [ {
    "severity" : "error",
    "code" : "invalid",
    "diagnostics" : "[0].item.type should be text or choice",
    "expression" : [ "contained" ]
  } ]
}

The contained answer options length of keyword reply is invalid

{
  "resourceType" : "OperationOutcome",
  "issue" : [ {
    "severity" : "error",
    "code" : "invalid",
    "diagnostics" : "Exceeds maximum length",
    "expression" : [ "contained[0].item[0].answerOptions" ]
  } ]
}

HTTP status: 401

Authorisation issue, for example a missing or expired bearer token.

Headers

Body

Content type: application/fhir+json

Examples

Invalid Access Token

{
  "resourceType" : "OperationOutcome",
  "issue" : [ {
    "severity" : "error",
    "code" : "forbidden",
    "diagnostics" : "Invalid Access Token"
  } ]
}

Expired Access Token

{
  "resourceType" : "OperationOutcome",
  "issue" : [ {
    "severity" : "error",
    "code" : "expired",
    "diagnostics" : "Access Token expired"
  } ]
}

HTTP status: 403

You are not authorised to perform this operation. For example, some onboarded client applications may be permitted to send Push Notifications but not In-app Messages, or vice versa.

Headers

Body

Content type: application/fhir+json

Example

{
  "resourceType" : "OperationOutcome",
  "issue" : [ {
    "severity" : "error",
    "code" : "security",
    "diagnostics" : "Supplier with ID e2efe52b-0cf2-4815-a3c9-7675c7962c54 does not have channel App Message permission"
  } ]
}

HTTP status: 429

You have exceeded your application’s rate limit or the API is currently receiving a high volume of requests.

Headers

Body

Content type: application/fhir+json

Examples

Your application has exceeded its quota

{
  "resourceType" : "OperationOutcome",
  "issue" : [ {
    "severity" : "error",
    "code" : "throttled",
    "diagnostics" : "Your application, my-app, has exceeded its quota of 100 requests every 1 minute(s) and is being rate limited."
  } ]
}

Your application has created a spike in traffic

{
  "resourceType" : "OperationOutcome",
  "issue" : [ {
    "severity" : "error",
    "code" : "throttled",
    "diagnostics" : "Your application, my-app, has created a spike in traffic and is being rate limited. Please reduce the frequency of your requests."
  } ]
}

API is receiving a high volume of requests

{
  "resourceType" : "OperationOutcome",
  "issue" : [ {
    "severity" : "error",
    "code" : "throttled",
    "diagnostics" : "This API is currently receiving a high volume of requests and is being rate limited."
  } ]
}

Send a push notification

Overview

Use this endpoint to send a native Apple or Android push notifications to mobile devices registered by specific users of the NHS App.

Push notifications will not be sent to users between the hours of 10pm and 6am UK time. If a valid request to send a push notification is processed between these hours, the push notification will be scheduled for delivery at 6am.

Recipients are specified by NHS number. A single request to this endpoint can send a push notification to a single NHS number. Push notifications will only be sent to users who have had their identity verified to 'high' (P9) level.

The body text of notifications can be up to 200 characters in length.

They must not contain:

• personally identifiable information (for example, the name of a user’s doctor)
• sensitive information (for example, details about a health condition)
• links to external websites

You can also optionally specify a URL for a page within the NHS App to be opened when the recipient taps on the push notification. If a URL is not specified, the NHS App will open on the home page.

The body of requests made to this endpoint are instances of HL7 FHIR R4 CommunicationRequest resources. This schema documentation describes which fields on that resource we require and support. The API is tolerant of (but will silently ignore) any additionally supplied optional fields. For example, we do not currently honour the doNotPerform or priority fields.

The outcome of communication requests can be determined using the daily receipt report endpoint. You may also create an endpoint into which NHS App can post the outcome of individual communication requests in realtime — we call this feature "realtime receipts". We have created (https://github.com/NHSDigital/nhs-app-api/tree/master/specifications-callbacks/realtime-receipts)[an Open API specification] detailing the behaviour of the endpoint that you should create to subscribe to realtime receipts.

Request

Headers

Body

Content type: application/fhir+json

Example

Sending a push notification

{
  "resourceType" : "CommunicationRequest",
  "identifier" : [ {
    "system" : "https://fhir.nhs.uk/NHSApp/campaign-id",
    "value" : "optional campaign id"
  }, {
    "system" : "https://fhir.nhs.uk/NHSApp/request-id",
    "value" : "optional request reference"
  } ],
  "status" : "active",
  "payload" : [ {
    "contentReference" : {
      "reference" : "https://www.nhsapp.service.nhs.uk/patient/messages/app-messaging",
      "display" : "You have a new message. The message may contain something important."
    }
  } ],
  "recipient" : [ {
    "type" : "Patient",
    "identifier" : {
      "system" : "https://fhir.nhs.uk/Id/nhs-number",
      "value" : "9903002157"
    }
  } ]
}

Response

HTTP status: 201

Request successfully received by the server and queued for sending to recipient.

Headers

Body

Content type: application/fhir+json

Example

{
  "resourceType" : "CommunicationRequest",
  "identifier" : [ {
    "system" : "https://fhir.nhs.uk/Id/nhs-app-communication-id",
    "value" : "54615138-df34-4a79-840d-dd07e9451519"
  }, {
    "system" : "https://fhir.nhs.uk/NHSApp/campaign-id",
    "value" : "optional campaign id"
  }, {
    "system" : "https://fhir.nhs.uk/NHSApp/request-id",
    "value" : "optional request reference"
  } ],
  "status" : "active",
  "payload" : [ {
    "contentReference" : {
      "reference" : "https://www.nhsapp.service.nhs.uk/patient/messages/app-messaging",
      "display" : "You have a new message. The message may contain something important."
    }
  } ],
  "recipient" : [ {
    "identifier" : {
      "system" : "https://fhir.nhs.uk/Id/nhs-number",
      "value" : "9903002157"
    }
  } ]
}

HTTP status: 400

There is an error in your request.

Headers

Body

Content type: application/fhir+json

Examples

Invalid resource type

{
  "resourceType" : "OperationOutcome",
  "issue" : [ {
    "severity" : "error",
    "code" : "invalid",
    "diagnostics" : "type (at Cannot locate type information for type 'communicationrequest')"
  } ]
}

Payload body text exceeds maximum length

{
  "resourceType" : "OperationOutcome",
  "issue" : [ {
    "severity" : "error",
    "code" : "invalid",
    "diagnostics" : "Exceeds maximum length",
    "expression" : [ "payload[0].contentReference.display" ]
  } ]
}

No recipient has been specified

{
  "resourceType" : "OperationOutcome",
  "issue" : [ {
    "severity" : "error",
    "code" : "invalid",
    "diagnostics" : "Not specified",
    "expression" : [ "recipient" ]
  } ]
}

A recipient has an invalid NHS number

{
  "resourceType" : "OperationOutcome",
  "issue" : [ {
    "severity" : "error",
    "code" : "invalid",
    "diagnostics" : "NHS Number is invalid",
    "expression" : [ "recipient[0].identifier.value" ]
  } ]
}

Too many recipients have been specified

{
  "resourceType" : "OperationOutcome",
  "issue" : [ {
    "severity" : "error",
    "code" : "invalid",
    "diagnostics" : "Exceeds maximum length",
    "expression" : [ "recipient" ]
  } ]
}

Multiple issues - no recipient has been specified and campaign ID exceeds maximum length

{
  "resourceType" : "OperationOutcome",
  "issue" : [ {
    "severity" : "error",
    "code" : "invalid",
    "diagnostics" : "Multiple Campaign IDs specified",
    "expression" : [ "identifier" ]
  }, {
    "severity" : "error",
    "code" : "invalid",
    "diagnostics" : "Exceeds maximum length",
    "expression" : [ "identifier[2].value" ]
  }, {
    "severity" : "error",
    "code" : "invalid",
    "diagnostics" : "Not specified",
    "expression" : [ "recipient" ]
  } ]
}

HTTP status: 401

Authorisation issue, for example a missing or expired bearer token.

Headers

Body

Content type: application/fhir+json

Examples

Invalid Access Token

{
  "resourceType" : "OperationOutcome",
  "issue" : [ {
    "severity" : "error",
    "code" : "forbidden",
    "diagnostics" : "Invalid Access Token"
  } ]
}

Expired Access Token

{
  "resourceType" : "OperationOutcome",
  "issue" : [ {
    "severity" : "error",
    "code" : "expired",
    "diagnostics" : "Access Token expired"
  } ]
}

HTTP status: 403

You are not authorised to perform this operation. For example, some onboarded client applications may be permitted to send Push Notifications but not In-app Messages, or vice versa.

Headers

Body

Content type: application/fhir+json

Example

{
  "resourceType" : "OperationOutcome",
  "issue" : [ {
    "severity" : "error",
    "code" : "security",
    "diagnostics" : "Supplier with ID 52a41839-f448-438b-98b8-903c3be15dc2 does not have channel Push Notification permission"
  } ]
}

HTTP status: 429

You have exceeded your application’s rate limit or the API is currently receiving a high volume of requests.

Headers

Body

Content type: application/fhir+json

Examples

Your application has exceeded its quota

{
  "resourceType" : "OperationOutcome",
  "issue" : [ {
    "severity" : "error",
    "code" : "throttled",
    "diagnostics" : "Your application, my-app, has exceeded its quota of 100 requests every 1 minute(s) and is being rate limited."
  } ]
}

Your application has created a spike in traffic

{
  "resourceType" : "OperationOutcome",
  "issue" : [ {
    "severity" : "error",
    "code" : "throttled",
    "diagnostics" : "Your application, my-app, has created a spike in traffic and is being rate limited. Please reduce the frequency of your requests."
  } ]
}

API is receiving a high volume of requests

{
  "resourceType" : "OperationOutcome",
  "issue" : [ {
    "severity" : "error",
    "code" : "throttled",
    "diagnostics" : "This API is currently receiving a high volume of requests and is being rate limited."
  } ]
}

Get details of NHS App users

Overview

Use 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 'high' (P9) level.

Client applications must only invoke this endpoint as agreed with the NHS App team, typically to retrieve details of patients at GP practices where their service is available.

This information can be used by client applications to determine whether it is appropriate to attempt to use the NHS App API to send in-app messages and push notifications to patients, or if alternative communication channels should be used instead.

The information provided by this endpoint is generated by a daily batch process. Client applications should cache and refresh local copies of this data accordingly.

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 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.

In order to test the pagination feature in the development and integration environments, use the ODS code T00001 to return a report with multiple pages.

Request

Query parameters

Headers

Response

HTTP status: 200

Information successfully returned.

Headers

Body

Content type: application/json

Example

[ {
  "nhsNumber" : "9074662803",
  "notificationsEnabled" : true
}, {
  "nhsNumber" : "9903002157",
  "notificationsEnabled" : false
} ]

HTTP status: 400

There is an error in your request.

Headers

Body

Content type: application/fhir+json

Examples

No ods-organisation-code parameter has been specified

{
  "resourceType" : "OperationOutcome",
  "issue" : [ {
    "severity" : "error",
    "code" : "invalid",
    "diagnostics" : "Not specified",
    "expression" : [ "ods-organisation-code" ]
  } ]
}

The supplied ods-organisation-code parameter is not in the correct format.

{
  "resourceType" : "OperationOutcome",
  "issue" : [ {
    "severity" : "error",
    "code" : "invalid",
    "diagnostics" : "Invalid format",
    "expression" : [ "ods-organisation-code" ]
  } ]
}

HTTP status: 401

Authorisation issue, for example a missing or expired bearer token.

Headers

Body

Content type: application/fhir+json

Examples

Invalid Access Token

{
  "resourceType" : "OperationOutcome",
  "issue" : [ {
    "severity" : "error",
    "code" : "forbidden",
    "diagnostics" : "Invalid Access Token"
  } ]
}

Expired Access Token

{
  "resourceType" : "OperationOutcome",
  "issue" : [ {
    "severity" : "error",
    "code" : "expired",
    "diagnostics" : "Access Token expired"
  } ]
}

HTTP status: 403

You are not authorised to perform this operation. Some client applications may not be permitted to access the patient report endpoint. To discuss granting your application access to this endpoint, contact the NHS App team.

Headers

Body

Content type: application/fhir+json

Example

{
  "resourceType" : "OperationOutcome",
  "issue" : [ {
    "severity" : "error",
    "code" : "security",
    "diagnostics" : "Supplier with ID e55091c0-1991-4a3f-b1fc-cec1928633ec does not have patient report access permission"
  } ]
}

HTTP status: 429

You have exceeded your application’s rate limit or the API is currently receiving a high volume of requests.

Headers

Body

Content type: application/fhir+json

Examples

Your application has exceeded its quota

{
  "resourceType" : "OperationOutcome",
  "issue" : [ {
    "severity" : "error",
    "code" : "throttled",
    "diagnostics" : "Your application, my-app, has exceeded its quota of 100 requests every 1 minute(s) and is being rate limited."
  } ]
}

Your application has created a spike in traffic

{
  "resourceType" : "OperationOutcome",
  "issue" : [ {
    "severity" : "error",
    "code" : "throttled",
    "diagnostics" : "Your application, my-app, has created a spike in traffic and is being rate limited. Please reduce the frequency of your requests."
  } ]
}

API is receiving a high volume of requests

{
  "resourceType" : "OperationOutcome",
  "issue" : [ {
    "severity" : "error",
    "code" : "throttled",
    "diagnostics" : "This API is currently receiving a high volume of requests and is being rate limited."
  } ]
}

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.
• Notified – a push notification is reported as having been successfully relayed to one or more native devices.
• 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.

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 (https://github.com/NHSDigital/nhs-app-api/tree/master/specifications-callbacks/realtime-receipts)[an Open API 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.

Request

Query parameters

Headers

Response

HTTP status: 200

Information successfully returned.

Headers

Body

Content type: application/json

Example

{
  "resourceType" : "Bundle",
  "type" : "searchset",
  "total" : 7,
  "link" : [ {
    "relation" : "self",
    "url" : "https://api.service.nhs.uk/nhs-app/communication/report/events/FHIR/R4/Task?day=2022-08-19&page=1"
  }, {
    "relation" : "last",
    "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/NHSApp/campaign-id",
        "value" : "optional campaign id"
      }, {
        "system" : "https://fhir.nhs.uk/NHSApp/request-id",
        "value" : "optional request reference"
      }, {
        "system" : "http://fhir.nhs.uk/Id/nhs-app-communication-id",
        "value" : "882cc757-5096-4565-9779-af25a751a65f"
      } ],
      "status" : "completed",
      "code" : {
        "coding" : [ {
          "system" : "https://fhir.nhs.uk/CodeSystem/NHSApp-Communication-Status",
          "code" : "Delivered"
        } ]
      },
      "authoredOn" : "2022-08-19T09:15:12+00:00",
      "lastModified" : "2022-08-19T09:15:56+00:00"
    }
  }, {
    "fullUrl" : "https://api.service.nhs.uk/nhs-app/communication/report/events/FHIR/R4/Task/a762b523-4e04-4a47-8cdb-e28b06dd3ea1",
    "resource" : {
      "id" : "a762b523-4e04-4a47-8cdb-e28b06dd3ea1",
      "resourceType" : "Task",
      "intent" : "order",
      "identifier" : [ {
        "system" : "https://fhir.nhs.uk/NHSApp/campaign-id",
        "value" : "optional campaign id"
      }, {
        "system" : "https://fhir.nhs.uk/NHSApp/request-id",
        "value" : "optional request reference"
      }, {
        "system" : "http://fhir.nhs.uk/Id/nhs-app-communication-id",
        "value" : "882cc757-5096-4565-9779-af25a751a65f"
      } ],
      "status" : "completed",
      "code" : {
        "coding" : [ {
          "system" : "https://fhir.nhs.uk/CodeSystem/NHSApp-Communication-Status",
          "code" : "Notified"
        } ]
      },
      "authoredOn" : "2022-08-19T09:15:12+00:00",
      "lastModified" : "2022-08-19T09:16:02+00:00"
    }
  }, {
    "fullUrl" : "https://api.service.nhs.uk/nhs-app/communication/report/events/FHIR/R4/Task/71fedfbc-d1c9-4342-8ee0-b8201b15f28f",
    "resource" : {
      "id" : "71fedfbc-d1c9-4342-8ee0-b8201b15f28f",
      "resourceType" : "Task",
      "intent" : "order",
      "identifier" : [ {
        "system" : "https://fhir.nhs.uk/NHSApp/campaign-id",
        "value" : "optional campaign id"
      }, {
        "system" : "https://fhir.nhs.uk/NHSApp/request-id",
        "value" : "optional request reference"
      }, {
        "system" : "http://fhir.nhs.uk/Id/nhs-app-communication-id",
        "value" : "882cc757-5096-4565-9779-af25a751a65f"
      } ],
      "status" : "completed",
      "code" : {
        "coding" : [ {
          "system" : "https://fhir.nhs.uk/CodeSystem/NHSApp-Communication-Status",
          "code" : "Read"
        } ]
      },
      "authoredOn" : "2022-08-19T09:15:12+00:00",
      "lastModified" : "2022-08-19T09:38:17+00:00"
    }
  }, {
    "fullUrl" : "https://api.service.nhs.uk/nhs-app/communication/report/events/FHIR/R4/Task/8c241d11-8957-4148-a298-0df6ffcb5521",
    "resource" : {
      "id" : "8c241d11-8957-4148-a298-0df6ffcb5521",
      "resourceType" : "Task",
      "intent" : "order",
      "identifier" : [ {
        "system" : "http://fhir.nhs.uk/Id/nhs-app-communication-id",
        "value" : "410baa9d-0b7e-4120-af1b-2f5b2656edf9"
      } ],
      "status" : "completed",
      "code" : {
        "coding" : [ {
          "system" : "https://fhir.nhs.uk/CodeSystem/NHSApp-Communication-Status",
          "code" : "Delivered"
        } ]
      },
      "authoredOn" : "2022-08-19T11:51:05+00:00",
      "lastModified" : "2022-08-19T11:51:07+00:00"
    }
  }, {
    "fullUrl" : "https://api.service.nhs.uk/nhs-app/communication/report/events/FHIR/R4/Task/f2c5b23f-387c-4c9e-87c9-346bd8bd9f03",
    "resource" : {
      "id" : "f2c5b23f-387c-4c9e-87c9-346bd8bd9f03",
      "resourceType" : "Task",
      "intent" : "order",
      "identifier" : [ {
        "system" : "http://fhir.nhs.uk/Id/nhs-app-communication-id",
        "value" : "410baa9d-0b7e-4120-af1b-2f5b2656edf9"
      } ],
      "status" : "completed",
      "code" : {
        "coding" : [ {
          "system" : "https://fhir.nhs.uk/CodeSystem/NHSApp-Communication-Status",
          "code" : "Unnotified"
        } ]
      },
      "authoredOn" : "2022-08-19T11:51:05+00:00",
      "lastModified" : "2022-08-19T11:51:34+00:00"
    }
  }, {
    "fullUrl" : "https://api.service.nhs.uk/nhs-app/communication/report/events/FHIR/R4/Task/0dc3ba21-ec8f-4d93-a74b-0d717c186dbe",
    "resource" : {
      "id" : "0dc3ba21-ec8f-4d93-a74b-0d717c186dbe",
      "resourceType" : "Task",
      "intent" : "order",
      "identifier" : [ {
        "system" : "http://fhir.nhs.uk/Id/nhs-app-communication-id",
        "value" : "410baa9d-0b7e-4120-af1b-2f5b2656edf9"
      } ],
      "status" : "completed",
      "code" : {
        "coding" : [ {
          "system" : "https://fhir.nhs.uk/CodeSystem/NHSApp-Communication-Status",
          "code" : "Read"
        } ]
      },
      "authoredOn" : "2022-08-19T11:51:05+00:00",
      "lastModified" : "2022-08-19T13:17:30+00:00"
    }
  }, {
    "fullUrl" : "https://api.service.nhs.uk/nhs-app/communication/report/events/FHIR/R4/Task/46fb07d6-e679-4ff8-97af-538935a707a3",
    "resource" : {
      "id" : "46fb07d6-e679-4ff8-97af-538935a707a3",
      "resourceType" : "Task",
      "intent" : "order",
      "identifier" : [ {
        "system" : "https://fhir.nhs.uk/NHSApp/campaign-id",
        "value" : "flu campaign 202208"
      }, {
        "system" : "http://fhir.nhs.uk/Id/nhs-app-communication-id",
        "value" : "01389fa3-2cb9-4440-b075-c4902b526fbc"
      } ],
      "status" : "rejected",
      "statusReason" : {
        "text" : "NHS number not found"
      },
      "code" : {
        "coding" : [ {
          "system" : "https://fhir.nhs.uk/CodeSystem/NHSApp-Communication-Status",
          "code" : "Rejected"
        } ]
      },
      "authoredOn" : "2021-08-19T15:20:52+00:00",
      "lastModified" : "2021-08-19T15:20:56+00:00"
    }
  } ]
}

HTTP status: 400

There is an error in your request.

Headers

Body

Content type: application/fhir+json

Examples

No day parameter has been specified

{
  "resourceType" : "OperationOutcome",
  "issue" : [ {
    "severity" : "error",
    "code" : "invalid",
    "diagnostics" : "Not specified",
    "expression" : [ "day" ]
  } ]
}

The supplied day parameter is not in the correct format.

{
  "resourceType" : "OperationOutcome",
  "issue" : [ {
    "severity" : "error",
    "code" : "invalid",
    "diagnostics" : "Invalid format",
    "expression" : [ "day" ]
  } ]
}

HTTP status: 401

Authorisation issue, for example a missing or expired bearer token.

Headers

Body

Content type: application/fhir+json

Examples

Invalid Access Token

{
  "resourceType" : "OperationOutcome",
  "issue" : [ {
    "severity" : "error",
    "code" : "forbidden",
    "diagnostics" : "Invalid Access Token"
  } ]
}

Expired Access Token

{
  "resourceType" : "OperationOutcome",
  "issue" : [ {
    "severity" : "error",
    "code" : "expired",
    "diagnostics" : "Access Token expired"
  } ]
}

HTTP status: 403

You are not authorised to perform this operation. Some client applications may not be permitted to access the receipt report endpoint. To discuss granting your application access to this endpoint, contact the NHS App team.

Headers

Body

Content type: application/fhir+json

Example

{
  "resourceType" : "OperationOutcome",
  "issue" : [ {
    "severity" : "error",
    "code" : "security",
    "diagnostics" : "Supplier with ID cdd248b8-cefb-404e-8da4-b79de3a9062a does not have Receipts report access permission"
  } ]
}

HTTP status: 429

You have exceeded your application’s rate limit or the API is currently receiving a high volume of requests.

Headers

Body

Content type: application/fhir+json

Examples

Your application has exceeded its quota

{
  "resourceType" : "OperationOutcome",
  "issue" : [ {
    "severity" : "error",
    "code" : "throttled",
    "diagnostics" : "Your application, my-app, has exceeded its quota of 100 requests every 1 minute(s) and is being rate limited."
  } ]
}

Your application has created a spike in traffic

{
  "resourceType" : "OperationOutcome",
  "issue" : [ {
    "severity" : "error",
    "code" : "throttled",
    "diagnostics" : "Your application, my-app, has created a spike in traffic and is being rate limited. Please reduce the frequency of your requests."
  } ]
}

API is receiving a high volume of requests

{
  "resourceType" : "OperationOutcome",
  "issue" : [ {
    "severity" : "error",
    "code" : "throttled",
    "diagnostics" : "This API is currently receiving a high volume of requests and is being rate limited."
  } ]
}

Last edited: 30 January 2023 4:55 pm