NHS App API

---

Endpoints: Communication

Send an in-app message

Overview

Use this endpoint to send an in-app message to one or more NHS App users.

Recipients are specified by NHS number. A single request to this endpoint can send an identical message to between 1 and 100 distinct NHS numbers. In-app messages will only be sent to users who have had their identity verified to 'high' (P9) level.

We support a subset of Markdown for describing the body text of in-app messages. 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.

Request

Headers

Body

Content type: application/json

Example

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)"
  } ],
  "sender" : {
    "display" : "Onboarded Third Party"
  },
  "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 recipients.

Headers

Body

Content type: application/fhir+json

Example

{
  "resourceType" : "CommunicationRequest",
  "identifier" : [ {
    "system" : "urn:ietf:rfc:3986",
    "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"
    }
  } ],
  "sender" : {
    "display" : "Onboarded Third Party"
  }
}

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 recipients have 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" ]
  } ]
}

Multiple issues - sender name is missing and campaign ID exceed 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" : [ "sender.display" ]
  } ]
}

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 an in-app message and push notification

Overview

Use this endpoint to send an in-app message followed by an associated native Apple or Android push notification to one or more NHS App users.

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 an identical message and push notification to between 1 and 100 distinct NHS numbers. 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 "You have a new message. This may contain important information.". To discuss changing this standard push notification content for your application, contact the NHS App team.

We are considering making an enhancement to allow the sender name of the in-app message content to be dynamically included in the content of the associated push notification. This may be of benefit if your application sends communications on behalf of several NHS organisations. You can track, comment, and vote for this feature on our interactive product backlog.

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

Request

Headers

Body

Content type: application/json

Example

Sending in app messages and push notifications

{
  "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)"
  } ],
  "sender" : {
    "display" : "Onboarded Third Party"
  },
  "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 recipients.

Headers

Body

Content type: application/fhir+json

Example

{
  "resourceType" : "CommunicationRequest",
  "identifier" : [ {
    "system" : "urn:ietf:rfc:3986",
    "value" : "58dccb28-671f-4237-8095-e80cf54861e1"
  }, {
    "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"
    }
  } ],
  "sender" : {
    "display" : "Onboarded Third Party"
  }
}

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 recipients have 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" ]
  } ]
}

Multiple issues - sender name is missing and campaign ID exceed 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" : [ "sender.display" ]
  } ]
}

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

Examples

Application is not permitted to send in-app messages

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

Application is not permitted to send push notifications

{
  "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."
  } ]
}

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 an identical push notification to between 1 and 100 distinct NHS numbers. 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.

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

Headers

Body

Content type: application/fhir+json

Example

{
  "resourceType" : "CommunicationRequest",
  "identifier" : [ {
    "system" : "urn:ietf:rfc:3986",
    "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 recipients have 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" ]
  } ]
}

Multiple issues - sender name is missing and campaign ID exceed 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" : [ "sender.display" ]
  } ]
}

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 a daily communication event report

Overview

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

An event will be included in this report detailing the outcome of attempting to send each communication to each individual recipient, for each channel (push notification or in-app message). Additionally, for in-app messages only, an event will be included in this report if and when the recipient reads the message.

The information provided by this endpoint is generated by a daily batch process. Note that events in the report may pertain to communication requests that were submitted on earlier days.

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.

Request

Query parameters

Headers

Response

HTTP status: 200

Information successfully returned.

Headers

Body

Content type: application/json

Example

[ {
  "eventDateTime" : "2021-08-05T13:28:58+00:00",
  "communicationId" : "a4d6af61-4302-48ab-b125-05daa8773836",
  "campaignId" : "Influenza_202108",
  "requestReference" : "AN_1234",
  "channel" : "AppMessage",
  "nhsNumber" : "9692113612",
  "communicationCreatedDateTime" : "2021-08-05T13:28:52+00:00",
  "event" : "Completed",
  "eventDetail" : null
}, {
  "eventDateTime" : "2021-08-05T13:30:01+00:00",
  "communicationId" : "a4d6af61-4302-48ab-b125-05daa8773836",
  "campaignId" : "Influenza_202108",
  "requestReference" : "AN_1234",
  "channel" : "PushNotification",
  "nhsNumber" : "9692113612",
  "communicationCreatedDateTime" : "2021-08-05T13:28:52+00:00",
  "event" : "Completed",
  "eventDetail" : null
}, {
  "eventDateTime" : "2021-08-05T13:28:00+00:00",
  "communicationId" : "a4d6af61-4302-48ab-b125-05daa8773836",
  "campaignId" : "Influenza_202108",
  "requestReference" : "AN_1234",
  "channel" : "AppMessage",
  "nhsNumber" : "9074732933",
  "communicationCreatedDateTime" : "2021-08-05T13:28:52+00:00",
  "event" : "Rejected",
  "eventDetail" : "NHS number not found"
}, {
  "eventDateTime" : "2021-08-05T13:28:01+00:00",
  "communicationId" : "a4d6af61-4302-48ab-b125-05daa8773836",
  "campaignId" : "Influenza_202108",
  "requestReference" : "AN_1234",
  "channel" : "PushNotification",
  "nhsNumber" : "9074732933",
  "communicationCreatedDateTime" : "2021-08-05T13:28:52+00:00",
  "event" : "Rejected",
  "eventDetail" : "NHS number not found"
}, {
  "eventDateTime" : "2021-08-05T13:28:58+00:00",
  "communicationId" : "a4d6af61-4302-48ab-b125-05daa8773836",
  "campaignId" : "Influenza_202108",
  "requestReference" : "AN_1234",
  "channel" : "AppMessage",
  "nhsNumber" : "9482026470",
  "communicationCreatedDateTime" : "2021-08-05T13:28:52+00:00",
  "event" : "Completed",
  "eventDetail" : null
}, {
  "eventDateTime" : "2021-08-05T13:30:02+00:00",
  "communicationId" : "a4d6af61-4302-48ab-b125-05daa8773836",
  "campaignId" : "Influenza_202108",
  "requestReference" : "AN_1234",
  "channel" : "PushNotification",
  "nhsNumber" : "9482026470",
  "communicationCreatedDateTime" : "2021-08-05T13:28:52+00:00",
  "event" : "Rejected",
  "eventDetail" : "Notification registration not found"
}, {
  "eventDateTime" : "2021-08-05T14:59:24+00:00",
  "communicationId" : "940a912d-13c2-466e-b9c2-46407532e89d",
  "campaignId" : null,
  "requestReference" : null,
  "channel" : "AppMessage",
  "nhsNumber" : "9133760004",
  "communicationCreatedDateTime" : "2021-08-05T14:59:16+00:00",
  "event" : "Failed",
  "eventDetail" : "Failure details"
}, {
  "eventDateTime" : "2021-08-05T14:59:26+00:00",
  "communicationId" : "940a912d-13c2-466e-b9c2-46407532e89d",
  "campaignId" : null,
  "requestReference" : null,
  "channel" : "PushNotification",
  "nhsNumber" : "9133760004",
  "communicationCreatedDateTime" : "2021-08-05T14:59:16+00:00",
  "event" : "Cancelled",
  "eventDetail" : "Associated App Message failed"
}, {
  "eventDateTime" : "2021-08-05T22:01:59+00:00",
  "communicationId" : "a4d6af61-4302-48ab-b125-05daa8773836",
  "campaignId" : "Influenza_202108",
  "requestReference" : "AN_1234",
  "channel" : "AppMessage",
  "nhsNumber" : "9692113612",
  "communicationCreatedDateTime" : "2021-08-05T13:28:52+00:00",
  "event" : "Read",
  "eventDetail" : null
}, {
  "eventDateTime" : "2021-08-05T23:07:19+00:00",
  "communicationId" : "a4d6af61-4302-48ab-b125-05daa8773836",
  "campaignId" : "Influenza_202108",
  "requestReference" : "AN_1234",
  "channel" : "AppMessage",
  "nhsNumber" : "9482026470",
  "communicationCreatedDateTime" : "2021-08-05T13:28:52+00:00",
  "event" : "Read",
  "eventDetail" : null
} ]

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

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."
  } ]
}