Overview
Use this API to engage with users of the NHS App - a simple and secure way for patients registered with a GP surgery in England to access a range of services on their smartphone or tablet.
You can:
- send in-app messages to specific users of the NHS App
- include keyword replies to in-app messages
- include free text replies to in-app messages
- send native Apple or Android push notifications to mobile devices registered by specific users of the NHS App
Who can use this API
To use this API, you must integrate with the NHS App.
Contact us before you begin any development work with this API, even if your service is already integrated.
API status and roadmap
This API is in production, beta.
To see our roadmap, or to suggest, comment or vote on features for this API, see our interactive product backlog.
If you would like to be involved in our beta programme or have any other queries, contact us.
Service level
This API is a silver plus service, meaning it is operational 24 x 7 x 365 but only supported during business hours (8am to 6pm), Monday to Friday excluding bank holidays. However, we respond to severity 1 and severity 2 incidents outside of business hours.
For more details, see service levels.
Technology
This API is RESTful.
It conforms to the FHIR global standard for health care data exchange, specifically to FHIR R4 (v4.0.1), except that it does not support the capabilities interaction.
It includes some country-specific FHIR extensions, which conform to FHIR UK Core, specifically fhir.r4.ukcore.stu1 0.5.1.
Specific rules for FHIR APIs
FHIR APIs are RESTful APIs that follow specific rules. In particular:
-
resource names are capitalised and singular, for example /CommunicationRequest
not /communicationRequests
-
array names are singular, for example recipient
not recipients
for communication recipients
-
data items that are country-specific and thus not included in the FHIR global base resources are usually wrapped in an extension
object
There are libraries and SDKs available to help with FHIR integration.
Network access
This API is available on the internet, and, indirectly, on the Health and Social Care Network (HSCN).
For more details see Network access for APIs.
Security and authorisation
This API is application-restricted,
meaning we authenticate the calling application but not the end user. In particular, the two FHIR CommunicationRequest
endpoints use signed JWT authentication - you authenticate your application by sending a signed JSON web token (JWT) to our OAuth 2.0 authorisation server. For more details see Application-restricted RESTful APIs - signed JWT authentication.
After following these steps to create an application and register the public key, the App ID should be provided to the NHS App onboarding team to grant your application permissions to the features that are appropriate to your use cases. If this step is not completed, all calls to this API will return responses with status code 403 Forbidden.
Environments and testing
API Environment |
NHS Login Environment |
Base URL |
Development |
Sandpit |
https://dev.api.service.nhs.uk/nhs-app/ |
Integration Testing |
Integration (AOS) |
https://int.api.service.nhs.uk/nhs-app/ |
Production |
Production |
https://api.service.nhs.uk/nhs-app/ |
Development
Our development environment:
We have created a Postman collection during internal development and testing of the API, which you may find useful when working with this environment.
Developers working with C# may also be interested in the integration tests that we have developed for the API, which make use of the fire.ly .NET SDK.
Integration testing
Our integration test environment:
- includes authorisation
- is for formal release testing and assurance when onboarding with NHS Login
- points to the Onboarding AOS NHS App environment, which in turn is using the NHS Login Integration (AOS) environment
- has a rate limit of 20 requests per second per application
For more details see integration testing with our RESTful APIs.
Production
Our production environment has a rate limit of 200 requests per second per application.
Onboarding
You need to get your product or service approved by us before you can use this API. We call this onboarding. The onboarding process can sometimes be quite long, so it’s worth planning well ahead.
Services not yet integrated
If your service is not yet integrated with the NHS App, you will need to follow our step by step process to onboard with us.
Integrated services
If your service is already integrated, and you now want to add notifications and messaging to your integration, you will need to take some extra steps before you can use this API. Explore notifications and messaging in the NHS App for guidelines and restrictions, and the documents you will need to complete.
To onboard for this API, please get in touch with the NHS App onboarding team at app.onboarding@nhs.net.
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.
Endpoints: Communication
Send an in-app message
post
/communication/in-app/FHIR/R4/CommunicationRequest
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
Name |
Description |
Authorization |
String
(^Bearer\ [[:ascii:]]+$)
An OAuth 2.0 bearer token.
Example: Bearer g1112R_ccQ1Ebbb4gtHBP1aaaNM
Required
|
X-Correlation-ID |
String
A unique message identifier. We use this to trace the message if you raise an issue with our helpdesk.
If provided, we recommend a GUID for uniqueness and convenience.
This is mirrored back in the response headers.
Example: b5bc6879-103e-4a78-975e-87e815c5da58
Optional
|
Body
Required
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"
}
}
}
object
|
Communication request to send a in-app message
|
resourceType
string
required
|
FHIR Resource Type – this must be CommunicationRequest .
|
identifier
array
|
An optional array of identifiers used to identify this request for later analysis.
We have defined the following two systems for identifiers that will be stored with the request:
- Campaign ID – denoted by system https://fhir.nhs.uk/NHSApp/campaign-id . This is an optional campaign identifier, used for later identification of a group of multiple communication requests. For example, this could be used to identify all messages that pertain to invitations for a particular vaccination programme.
- Request Reference – denoted by system https://fhir.nhs.uk/NHSApp/request-id . This is an optional request identifier, used for later identification of a specific request.
Note that these identifier system names are case-sensitive. The values provided for each of these two identifiers are limited to 50 characters, and must not match the regular expression <(.|\n)*?> .
No more than one campaign ID and one request reference can be supplied with each request.
The API will not reject requests that contain other identifier systems, but these values will be ignored and not recorded against the request.
When a CommunicationRequest resource is returned in the response body to a successful request, this array will also include a globally unique identifier assigned by the API, with the system https://fhir.nhs.uk/Id/nhs-app-communication-id . This is the same logical ID contained within the Location header of the successful response.
|
object
|
|
system
string
uri
|
The namespace for the identifier value
Example: https://fhir.nhs.uk/NHSApp/campaign-id
|
value
string
|
The value of the identifier
Example: Optional campaign ID
|
status
string
required
|
Request Status of the message. This must always be active (case-sensitive).
Default: active
|
payload
array
required
|
The body text of the message to be displayed in the NHS App
|
object
|
|
contentString
string
required
|
The body text of the message to be displayed in the NHS App. We support a subset of Markdown for in-app messages.
Currently supported Markdown syntax:
-
Emphasis
-
Headings
-
Heading 2 ## Heading 2
-
Heading 3 ### Heading 3
-
Lists
-
Bulleted list:
* Item1
* Item2
* Item3
-
Ordered lists
1. Item1
2. Item2
3. Item3
-
Links with text [Link text](https://en.wikipedia.org/wiki/Markdown)
-
Links with title [Link text](https://en.wikipedia.org/wiki/Markdown, "Title text")
-
Images 
-
Line break, two or more spaces followed by return
Forcing a line-break   <--(two spaces)
Next line
Pattern: must not match <(.|\n)*?>
Max length: 5000
Example: 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
|
contained
array
|
An optional array of FHIR resource object used for a keyword & free text replies. Must contain only one item in the array.
Min items: 1
Max items: 1
|
object
|
|
resourceType
string
required
|
FHIR Resource Type – this must be Questionnaire
|
id
string
required
|
Id of the Questionnaire resource type
|
status
string
required
|
Questionnaire status for the message. This must always be active (case-sensitive)
Default: active
|
item
array
required
|
An array containing the type of the message reply. Must contain only one item in the array
Min items: 1
Max items: 1
|
object
|
|
linkId
string
required
|
Any unique Id which must be a string
|
type
string
required
|
Type must be text for the free text and choice for the keyword replies messages
|
answerOption
array
|
An optional array containing valueCoding objects for keyword replies. Only required for keyword reply messages
Min items: 1
Max items: 6
|
object
|
|
valueCoding
object
|
An optional object contains code. Only required for keyword reply messages
|
code
string
|
A string code that would be shown to the patient for selection. Only required for keyword reply messages
|
extension
array
|
An optional array of FHIR extension resource used for a keyword & free text replies. Must be present when the contained field is available in the request
Min items: 1
Max items: 1
|
object
|
|
url
string
required
|
This should be https://fhir.nhs.uk/NHSApp/answers
Default: https://fhir.nhs.uk/NHSApp/answers
|
valueReference
object
required
|
|
reference
string
required
|
The reference value should be same as Questionnaire resource Id. Must have '#' prefix
|
recipient
array
required
|
An array containing a single NHS number corresponding to the patient to whom this in-app message should be sent. Each communication may be sent to only a single recipient.
Min items: 1
Max items: 1
|
object
|
|
type
string
|
FHIR resource type that the reference refers to. This should be Patient .
Example: Patient
|
identifier
object
|
Identifier of a recipient. This should be an NHS number.
|
system
string
uri
required
|
The system that the identifier belongs to. This should be https://fhir.nhs.uk/Id/nhs-number
Default: https://fhir.nhs.uk/Id/nhs-number
|
value
string
required
|
The patient's NHS number. The primary identifier of a patient, unique within NHS England and Wales. Always 10 digits and must be a valid NHS number.
Pattern: ^\d{10}$
Example: 9903002157
|
requester
object
required
|
The requester who initiated the communication and would like to send an in-app message to the patient.
|
type
string
|
FHIR resource type that the organization code refers to. This should be Organization .
Example: Organization
|
identifier
object
|
Identifier and system of identification used for this Organisation.
|
system
string
uri
required
|
URL for the Organisation Data Service - who are responsible for publishing codes that identify organisations and individuals across health and social care. This should be https://fhir.nhs.uk/Id/ods-organization-code
Default: https://fhir.nhs.uk/Id/ods-organization-code
|
value
string
required
|
ODS code of the requester who initiated the communication and would like to send an in-app message to the patient.
Pattern: ^[0-9A-Z]+$
Example: B82041
|
Response
HTTP status: 201
Request successfully received by the server and queued for sending to recipient.
Headers
Name |
Description |
Location |
String
The location of the newly-created resource.
|
X-Correlation-ID |
String
The X-Correlation-ID from the request header, if supplied, mirrored back.
Example: 11C46F5F-CDEF-4865-94B2-0EE0EDCC26DA
|
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"
}
}
}
object
|
Communication response body for a successful in-app message request.
|
resourceType
string
|
FHIR Resource Type – this will be CommunicationRequest .
|
identifier
array
|
An array of identifiers used to identify this request.
This array will always include a globally unique identifier assigned by the API, with the system https://fhir.nhs.uk/Id/nhs-app-communication-id .
It will include optional identifiers that were provided in the request if the API recognised the identifier system name.
|
object
|
|
system
string
uri
|
The namespace of the identifier value.
Example: https://fhir.nhs.uk/Id/nhs-app-communication-id
|
value
string
|
The value of the identifier.
Example: 8f7ec136-66eb-4a9e-97ca-5c7a53d2710c
|
status
string
|
Request Status of the message – this will be active .
|
payload
array
|
The body text of the message to be displayed in the NHS App.
|
object
|
|
contentString
string
|
The body text of the message to be displayed in the NHS App.
Example: 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)
|
contained
array
|
An optional array of FHIR resource object. Will contain only one item in the array
|
object
|
|
resourceType
string
|
FHIR Resource Type – this will be Questionnaire
|
id
string
|
Id of the Questionnaire resource type sent in the request
|
status
string
|
Questionnaire Status for the message. This will be active (case-sensitive)
|
item
array
|
An array containing the type of the message reply
|
object
|
|
linkId
string
|
Id specified in the request
|
type
string
|
Type specified in the request
|
answerOption
array
|
An optional array containing valueCoding objects
|
object
|
|
valueCoding
object
|
An optional object contains code
|
code
string
|
|
extension
array
|
An optional array of FHIR extension resource as specified in the request
|
object
|
|
url
string
|
This will be https://fhir.nhs.uk/NHSApp/answers
|
valueReference
object
|
|
reference
string
|
The reference value will be same as Questionnaire resource id from request prefixed with '#'
|
recipient
array
|
An array containing a single NHS number corresponding to the patient to whom this in-app message was sent.
|
object
|
|
identifier
object
|
Identifier of a recipient. This will be an NHS number.
|
system
string
uri
|
The system that the identifier belongs to. This will be https://fhir.nhs.uk/Id/nhs-number .
Default: https://fhir.nhs.uk/Id/nhs-number
|
value
string
|
The patient's NHS number.
Pattern: ^\d{10}$
Example: 9903002157
|
requester
object
|
The requester who has sent the request for in-app message to the patient.
|
type
string
|
FHIR resource type that the organization code refers to. This should be Organization .
Example: Organization
|
identifier
object
|
|
system
string
uri
|
The namespace of the identifier value.
|
value
string
|
The value of the identifier.
Example: B82041
|
HTTP status: 400
There is an error in your request.
Headers
Name |
Description |
X-Correlation-ID |
String
The X-Correlation-ID from the request header, if supplied, mirrored back.
Example: 11C46F5F-CDEF-4865-94B2-0EE0EDCC26DA
|
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" ]
} ]
}
object
|
|
resourceType
string
|
Default: OperationOutcome
|
issue
array
|
List of issues that have occurred.
Min items: 1
|
object
|
|
severity
string
required
|
Allowed values: fatal, error, warning, information
|
code
string
required
|
Allowed values: expired, forbidden, invalid, processing, security, throttled
|
diagnostics
string
|
Additional diagnostic information about the issue.
Example: Not specified
|
expression
array
|
FHIRPath of element(s) related to the error.
|
string
|
Example: requester.identifier
|
HTTP status: 401
Authorisation issue, for example a missing or expired bearer token.
Headers
Name |
Description |
X-Correlation-ID |
String
The X-Correlation-ID from the request header, if supplied, mirrored back.
Example: 11C46F5F-CDEF-4865-94B2-0EE0EDCC26DA
|
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"
} ]
}
object
|
|
resourceType
string
|
Default: OperationOutcome
|
issue
array
|
List of issues that have occurred.
Min items: 1
|
object
|
|
severity
string
required
|
Allowed values: fatal, error, warning, information
|
code
string
required
|
Allowed values: expired, forbidden, invalid, processing, security, throttled
|
diagnostics
string
|
Additional diagnostic information about the issue.
Example: Not specified
|
expression
array
|
FHIRPath of element(s) related to the error.
|
string
|
Example: requester.identifier
|
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
Name |
Description |
X-Correlation-ID |
String
The X-Correlation-ID from the request header, if supplied, mirrored back.
Example: 11C46F5F-CDEF-4865-94B2-0EE0EDCC26DA
|
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"
} ]
}
object
|
|
resourceType
string
|
Default: OperationOutcome
|
issue
array
|
List of issues that have occurred.
Min items: 1
|
object
|
|
severity
string
required
|
Allowed values: fatal, error, warning, information
|
code
string
required
|
Allowed values: expired, forbidden, invalid, processing, security, throttled
|
diagnostics
string
|
Additional diagnostic information about the issue.
Example: Not specified
|
expression
array
|
FHIRPath of element(s) related to the error.
|
string
|
Example: requester.identifier
|
HTTP status: 429
You have exceeded your application’s rate limit or the API is currently receiving a high volume of requests.
Headers
Name |
Description |
X-Correlation-ID |
String
The X-Correlation-ID from the request header, if supplied, mirrored back.
Example: 11C46F5F-CDEF-4865-94B2-0EE0EDCC26DA
|
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."
} ]
}
object
|
|
resourceType
string
|
Default: OperationOutcome
|
issue
array
|
List of issues that have occurred.
Min items: 1
|
object
|
|
severity
string
required
|
Allowed values: fatal, error, warning, information
|
code
string
required
|
Allowed values: expired, forbidden, invalid, processing, security, throttled
|
diagnostics
string
|
Additional diagnostic information about the issue.
Example: Not specified
|
expression
array
|
FHIRPath of element(s) related to the error.
|
string
|
Example: requester.identifier
|
Send a push notification
post
/communication/notification/FHIR/R4/CommunicationRequest
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
Name |
Description |
Authorization |
String
(^Bearer\ [[:ascii:]]+$)
An OAuth 2.0 bearer token.
Example: Bearer g1112R_ccQ1Ebbb4gtHBP1aaaNM
Required
|
X-Correlation-ID |
String
A unique message identifier. We use this to trace the message if you raise an issue with our helpdesk.
If provided, we recommend a GUID for uniqueness and convenience.
This is mirrored back in the response headers.
Example: b5bc6879-103e-4a78-975e-87e815c5da58
Optional
|
Body
Required
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"
}
} ]
}
object
|
Communication request for sending a push notification
|
resourceType
string
required
|
FHIR Resource Type – this must be CommunicationRequest .
|
identifier
array
|
An optional array of identifiers used to identify this request for later analysis.
We have defined the following two systems for identifiers that will be stored with the request:
- Campaign ID – denoted by system https://fhir.nhs.uk/NHSApp/campaign-id . This is an optional campaign identifier, used for later identification of a group of multiple communication requests. For example, this could be used to identify all messages that pertain to invitations for a particular vaccination programme.
- Request Reference – denoted by system https://fhir.nhs.uk/NHSApp/request-id . This is an optional request identifier, used for later identification of a specific request.
Note that these identifier system names are case-sensitive. The values provided for each of these two identifiers are limited to 50 characters, and must not match the regular expression <(.|\n)*?> .
No more than one campaign ID and one request reference can be supplied with each request.
The API will not reject requests that contain other identifier systems, but these values will be ignored and not recorded against the request.
When a CommunicationRequest resource is returned in the response body to a successful request, this array will also include a globally unique identifier assigned by the API, with the system https://fhir.nhs.uk/Id/nhs-app-communication-id . This is the same logical ID contained within the Location header of the successful response.
|
object
|
|
system
string
uri
|
The namespace for the identifier value
Example: https://fhir.nhs.uk/NHSApp/campaign-id
|
value
string
|
The value of the identifier
Example: Optional campaign ID
|
status
string
required
|
Request Status of the message. This must always be active (case-sensitive).
Default: active
|
payload
array
required
|
The body text to be displayed in the push notification.
|
object
|
|
contentReference
object
required
|
Structure of body text in the push notification.
|
reference
string
url
required
|
The URL to a page within the NHS App to be opened when the notification is tapped. If this property is not specified, the App will open on the home screen.
Max length: 1000
Example: https://www.nhsapp.service.nhs.uk/patient/messages/app-messaging
|
display
string
required
|
The communication content to appear as a native Apple or Android push notification. Notifications must use unicode characters. 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 Notifications can only link to pages and features within the NHS App.
Max length: 200
Example: You have a new message. The message may contain something important.
|
recipient
array
required
|
An array containing a single NHS number corresponding to the patient to whom this push notification should be sent. Each communication may be sent to only a single recipient.
Min items: 1
Max items: 1
|
object
|
|
type
string
|
FHIR resource type that the reference refers to. This should be Patient .
Example: Patient
|
identifier
object
|
Identifier of a recipient. This should be an NHS number.
|
system
string
uri
required
|
The system that the identifier belongs to. This should be https://fhir.nhs.uk/Id/nhs-number
Default: https://fhir.nhs.uk/Id/nhs-number
|
value
string
required
|
The patient's NHS number. The primary identifier of a patient, unique within NHS England and Wales. Always 10 digits and must be a valid NHS number.
Pattern: ^\d{10}$
Example: 9903002157
|
Response
HTTP status: 201
Request successfully received by the server and queued for sending to recipient.
Headers
Name |
Description |
Location |
String
The location of the newly-created resource.
|
X-Correlation-ID |
String
The X-Correlation-ID from the request header, if supplied, mirrored back.
Example: 11C46F5F-CDEF-4865-94B2-0EE0EDCC26DA
|
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"
}
} ]
}
object
|
Communication response body from a successful push notification request.
|
resourceType
string
|
FHIR Resource Type – this will be CommunicationRequest .
|
identifier
array
|
An array of identifiers used to identify this request.
This array will always include a globally unique identifier assigned by the API, with the system https://fhir.nhs.uk/Id/nhs-app-communication-id .
It will include optional identifiers that were provided in the request if the API recognised the identifier system name.
|
object
|
|
system
string
uri
|
The namespace of the identifier value.
Example: https://fhir.nhs.uk/Id/nhs-app-communication-id
|
value
string
|
The value of the identifier.
Example: 54615138-df34-4a79-840d-dd07e9451519
|
status
string
|
Request Status of the message – this will be active
|
payload
array
|
The body text to be displayed in the push notification.
|
object
|
|
contentReference
object
|
Structure of body text in the push notification.
|
reference
string
url
|
The URL to a page within the NHS App to be opened when the notification is tapped.
Example: https://www.nhsapp.service.nhs.uk/patient/messages/app-messaging
|
display
string
|
The communication content to appear as a native Apple or Android push notification.
Example: You have a new message. The message may contain something important.
|
recipient
array
|
An array containing a single NHS number corresponding to the patient to whom this push notification was sent.
|
object
|
|
identifier
object
|
Identifier of a recipient. This will be an NHS number.
|
system
string
uri
|
The system that the identifier belongs to. This will be https://fhir.nhs.uk/Id/nhs-number .
Default: https://fhir.nhs.uk/Id/nhs-number
|
value
string
|
The patient's NHS number.
Pattern: ^\d{10}$
Example: 9903002157
|
HTTP status: 400
There is an error in your request.
Headers
Name |
Description |
X-Correlation-ID |
String
The X-Correlation-ID from the request header, if supplied, mirrored back.
Example: 11C46F5F-CDEF-4865-94B2-0EE0EDCC26DA
|
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" ]
} ]
}
object
|
|
resourceType
string
|
Default: OperationOutcome
|
issue
array
|
List of issues that have occurred.
Min items: 1
|
object
|
|
severity
string
required
|
Allowed values: fatal, error, warning, information
|
code
string
required
|
Allowed values: expired, forbidden, invalid, processing, security, throttled
|
diagnostics
string
|
Additional diagnostic information about the issue.
Example: Not specified
|
expression
array
|
FHIRPath of element(s) related to the error.
|
string
|
Example: requester.identifier
|
HTTP status: 401
Authorisation issue, for example a missing or expired bearer token.
Headers
Name |
Description |
X-Correlation-ID |
String
The X-Correlation-ID from the request header, if supplied, mirrored back.
Example: 11C46F5F-CDEF-4865-94B2-0EE0EDCC26DA
|
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"
} ]
}
object
|
|
resourceType
string
|
Default: OperationOutcome
|
issue
array
|
List of issues that have occurred.
Min items: 1
|
object
|
|
severity
string
required
|
Allowed values: fatal, error, warning, information
|
code
string
required
|
Allowed values: expired, forbidden, invalid, processing, security, throttled
|
diagnostics
string
|
Additional diagnostic information about the issue.
Example: Not specified
|
expression
array
|
FHIRPath of element(s) related to the error.
|
string
|
Example: requester.identifier
|
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
Name |
Description |
X-Correlation-ID |
String
The X-Correlation-ID from the request header, if supplied, mirrored back.
Example: 11C46F5F-CDEF-4865-94B2-0EE0EDCC26DA
|
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"
} ]
}
object
|
|
resourceType
string
|
Default: OperationOutcome
|
issue
array
|
List of issues that have occurred.
Min items: 1
|
object
|
|
severity
string
required
|
Allowed values: fatal, error, warning, information
|
code
string
required
|
Allowed values: expired, forbidden, invalid, processing, security, throttled
|
diagnostics
string
|
Additional diagnostic information about the issue.
Example: Not specified
|
expression
array
|
FHIRPath of element(s) related to the error.
|
string
|
Example: requester.identifier
|
HTTP status: 429
You have exceeded your application’s rate limit or the API is currently receiving a high volume of requests.
Headers
Name |
Description |
X-Correlation-ID |
String
The X-Correlation-ID from the request header, if supplied, mirrored back.
Example: 11C46F5F-CDEF-4865-94B2-0EE0EDCC26DA
|
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."
} ]
}
object
|
|
resourceType
string
|
Default: OperationOutcome
|
issue
array
|
List of issues that have occurred.
Min items: 1
|
object
|
|
severity
string
required
|
Allowed values: fatal, error, warning, information
|
code
string
required
|
Allowed values: expired, forbidden, invalid, processing, security, throttled
|
diagnostics
string
|
Additional diagnostic information about the issue.
Example: Not specified
|
expression
array
|
FHIRPath of element(s) related to the error.
|
string
|
Example: requester.identifier
|
Get details of NHS App users
get
/communication/report/patients
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
Name |
Description |
ods-organisation-code |
String
The Organisation Data Service (ODS) code of the GP practice for which to retrieve a list of NHS App users.
Not case sensitive.
Pattern: /^[A-Za-z]\\d{5}$|^[A-Za-z]\\d[A-Za-z]\\d[A-Za-z]$/
Example: Y00001
Required
|
page |
Integer
(int32)
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.
Example: 2
Optional
|
Headers
Name |
Description |
Authorization |
String
(^Bearer\ [[:ascii:]]+$)
An OAuth 2.0 bearer token.
Example: Bearer g1112R_ccQ1Ebbb4gtHBP1aaaNM
Required
|
X-Correlation-ID |
String
A unique message identifier. We use this to trace the message if you raise an issue with our helpdesk.
If provided, we recommend a GUID for uniqueness and convenience.
This is mirrored back in the response headers.
Example: b5bc6879-103e-4a78-975e-87e815c5da58
Optional
|
Response
HTTP status: 200
Information successfully returned.
Headers
Name |
Description |
Link |
String
Comma-separated links to the last page and (if applicable) next page of paginated results.
|
X-Correlation-ID |
String
The X-Correlation-ID from the request header, if supplied, mirrored back.
Example: 11C46F5F-CDEF-4865-94B2-0EE0EDCC26DA
|
Body
Content type: application/json
Example
[ {
"nhsNumber" : "9074662803",
"notificationsEnabled" : true
}, {
"nhsNumber" : "9903002157",
"notificationsEnabled" : false
} ]
array
|
An array of details of patients registered with the NHS App.
|
object
|
Details of a single patient registered with the NHS App.
|
nhsNumber
string
^\d{10}$
|
The patient's NHS number.
Example: 9903002157
|
notificationsEnabled
boolean
|
Indicates whether the patient has enabled native Android or Apple push notifications on at least one device.
Example: true
|
HTTP status: 400
There is an error in your request.
Headers
Name |
Description |
X-Correlation-ID |
String
The X-Correlation-ID from the request header, if supplied, mirrored back.
Example: 11C46F5F-CDEF-4865-94B2-0EE0EDCC26DA
|
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" ]
} ]
}
object
|
|
resourceType
string
|
Default: OperationOutcome
|
issue
array
|
List of issues that have occurred.
Min items: 1
|
object
|
|
severity
string
required
|
Allowed values: fatal, error, warning, information
|
code
string
required
|
Allowed values: expired, forbidden, invalid, processing, security, throttled
|
diagnostics
string
|
Additional diagnostic information about the issue.
Example: Not specified
|
expression
array
|
FHIRPath of element(s) related to the error.
|
string
|
Example: requester.identifier
|
HTTP status: 401
Authorisation issue, for example a missing or expired bearer token.
Headers
Name |
Description |
X-Correlation-ID |
String
The X-Correlation-ID from the request header, if supplied, mirrored back.
Example: 11C46F5F-CDEF-4865-94B2-0EE0EDCC26DA
|
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"
} ]
}
object
|
|
resourceType
string
|
Default: OperationOutcome
|
issue
array
|
List of issues that have occurred.
Min items: 1
|
object
|
|
severity
string
required
|
Allowed values: fatal, error, warning, information
|
code
string
required
|
Allowed values: expired, forbidden, invalid, processing, security, throttled
|
diagnostics
string
|
Additional diagnostic information about the issue.
Example: Not specified
|
expression
array
|
FHIRPath of element(s) related to the error.
|
string
|
Example: requester.identifier
|
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
Name |
Description |
X-Correlation-ID |
String
The X-Correlation-ID from the request header, if supplied, mirrored back.
Example: 11C46F5F-CDEF-4865-94B2-0EE0EDCC26DA
|
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"
} ]
}
object
|
|
resourceType
string
|
Default: OperationOutcome
|
issue
array
|
List of issues that have occurred.
Min items: 1
|
object
|
|
severity
string
required
|
Allowed values: fatal, error, warning, information
|
code
string
required
|
Allowed values: expired, forbidden, invalid, processing, security, throttled
|
diagnostics
string
|
Additional diagnostic information about the issue.
Example: Not specified
|
expression
array
|
FHIRPath of element(s) related to the error.
|
string
|
Example: requester.identifier
|
HTTP status: 429
You have exceeded your application’s rate limit or the API is currently receiving a high volume of requests.
Headers
Name |
Description |
X-Correlation-ID |
String
The X-Correlation-ID from the request header, if supplied, mirrored back.
Example: 11C46F5F-CDEF-4865-94B2-0EE0EDCC26DA
|
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."
} ]
}
object
|
|
resourceType
string
|
Default: OperationOutcome
|
issue
array
|
List of issues that have occurred.
Min items: 1
|
object
|
|
severity
string
required
|
Allowed values: fatal, error, warning, information
|
code
string
required
|
Allowed values: expired, forbidden, invalid, processing, security, throttled
|
diagnostics
string
|
Additional diagnostic information about the issue.
Example: Not specified
|
expression
array
|
FHIRPath of element(s) related to the error.
|
string
|
Example: requester.identifier
|
Get a daily receipt report
get
/communication/report/receipts/FHIR/R4/Task
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
Name |
Description |
day |
date
(date)
The day for which to retrieve a receipt report.
Example: 2022-08-22
Required
|
page |
Integer
(int32)
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.
Example: 2
Optional
|
Headers
Name |
Description |
Authorization |
String
(^Bearer\ [[:ascii:]]+$)
An OAuth 2.0 bearer token.
Example: Bearer g1112R_ccQ1Ebbb4gtHBP1aaaNM
Required
|
X-Correlation-ID |
String
A unique message identifier. We use this to trace the message if you raise an issue with our helpdesk.
If provided, we recommend a GUID for uniqueness and convenience.
This is mirrored back in the response headers.
Example: b5bc6879-103e-4a78-975e-87e815c5da58
Optional
|
Response
HTTP status: 200
Information successfully returned.
Headers
Name |
Description |
Link |
String
Comma-separated links to the last page and (if applicable) next page of paginated results.
|
X-Correlation-ID |
String
The X-Correlation-ID from the request header, if supplied, mirrored back.
Example: 11C46F5F-CDEF-4865-94B2-0EE0EDCC26DA
|
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"
}
} ]
}
object
|
Bundle resource containing tasks
A bundle resource containing tasks representing receipts relating to in-app messages and push notifications that you have previously sent to NHS App users.
|
resourceType
string
required
|
Allowed values: Bundle
|
type
string
required
|
Allowed values: searchset
|
link
array
required
|
Min items: 1
Max items: 3
|
object
|
|
relation
string
required
|
Allowed values: self, last, next
|
url
string
required
|
Example: https://api.service.nhs.uk/nhs-app/communication/report/events/FHIR/R4/Task?day=2022-08-19&page=1
|
entry
array
required
|
|
object
|
Details a single receipt relating to an in-app message or push notification that was previously sent to an NHS App user.
|
fullUrl
string
required
|
Example: https://api.service.nhs.uk/nhs-app/communication/report/events/FHIR/R4/Task/b2ac2ae7-1a24-4e90-8f3f-9a62c6ebb4e7
|
resource
object
required
|
Details a single receipt relating to an in-app message or push notification that was previously sent to an NHS App user.
|
id
string
required
|
ID to uniquely identify this receipt. Note that this is not the ID of the original communication request, which is included in the identifiers array.
Example: b2ac2ae7-1a24-4e90-8f3f-9a62c6ebb4e7
|
resourceType
string
required
|
Allowed values: Task
|
intent
string
required
|
Allowed values: order
|
identifier
array
|
An array of identifiers used to identify the original communication request that is referenced by this receipt.
This array will always include a globally unique identifier for the communication request assigned by the API, with the system https://fhir.nhs.uk/Id/nhs-app-communication-id . Note that several receipts may be included for each communication ID – for example a single in-app message might generate a Delivered receipt and a Read receipt.
It will include optional identifiers that were provided in the original communication request if the API recognised the identifier system name.
|
object
|
|
system
string
uri
|
The namespace of the identifier value.
Example: https://fhir.nhs.uk/Id/nhs-app-communication-id
|
value
string
|
The value of the identifier.
Example: 882cc757-5096-4565-9779-af25a751a65f
|
status
string
required
|
This will be rejected for receipts conveying that a communication request has been rejected, and completed for the other receipt types.
Allowed values: rejected, completed
|
statusReason
string
|
For rejected receipts only, this property will contain an explanation of why the rejection occurred.
Example: NHS number not found
|
code
object
required
|
Indication of the type of event that occurred.
|
coding
array
required
|
|
oneOf
|
|
object
|
|
system
string
required
|
Allowed values: https://fhir.nhs.uk/CodeSystem/NHSApp-Communication-Status
|
code
string
required
|
Allowed values: Delivered, Rejected, Notified, Unnotified, Read
|
authoredOn
string
date-time
required
|
The UTC datetime at which the original communication request was received.
Example: 2022-08-19T09:15:12Z
|
lastModified
string
date-time
required
|
The UTC datetime at which the event occurred. Note that this may be several days after the datetime at which the communication request was originally made (particularly for Read receipts).
Example: 2022-08-19T09:15:56Z
|
HTTP status: 400
There is an error in your request.
Headers
Name |
Description |
X-Correlation-ID |
String
The X-Correlation-ID from the request header, if supplied, mirrored back.
Example: 11C46F5F-CDEF-4865-94B2-0EE0EDCC26DA
|
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" ]
} ]
}
object
|
|
resourceType
string
|
Default: OperationOutcome
|
issue
array
|
List of issues that have occurred.
Min items: 1
|
object
|
|
severity
string
required
|
Allowed values: fatal, error, warning, information
|
code
string
required
|
Allowed values: expired, forbidden, invalid, processing, security, throttled
|
diagnostics
string
|
Additional diagnostic information about the issue.
Example: Not specified
|
expression
array
|
FHIRPath of element(s) related to the error.
|
string
|
Example: requester.identifier
|
HTTP status: 401
Authorisation issue, for example a missing or expired bearer token.
Headers
Name |
Description |
X-Correlation-ID |
String
The X-Correlation-ID from the request header, if supplied, mirrored back.
Example: 11C46F5F-CDEF-4865-94B2-0EE0EDCC26DA
|
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"
} ]
}
object
|
|
resourceType
string
|
Default: OperationOutcome
|
issue
array
|
List of issues that have occurred.
Min items: 1
|
object
|
|
severity
string
required
|
Allowed values: fatal, error, warning, information
|
code
string
required
|
Allowed values: expired, forbidden, invalid, processing, security, throttled
|
diagnostics
string
|
Additional diagnostic information about the issue.
Example: Not specified
|
expression
array
|
FHIRPath of element(s) related to the error.
|
string
|
Example: requester.identifier
|
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
Name |
Description |
X-Correlation-ID |
String
The X-Correlation-ID from the request header, if supplied, mirrored back.
Example: 11C46F5F-CDEF-4865-94B2-0EE0EDCC26DA
|
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"
} ]
}
object
|
|
resourceType
string
|
Default: OperationOutcome
|
issue
array
|
List of issues that have occurred.
Min items: 1
|
object
|
|
severity
string
required
|
Allowed values: fatal, error, warning, information
|
code
string
required
|
Allowed values: expired, forbidden, invalid, processing, security, throttled
|
diagnostics
string
|
Additional diagnostic information about the issue.
Example: Not specified
|
expression
array
|
FHIRPath of element(s) related to the error.
|
string
|
Example: requester.identifier
|
HTTP status: 429
You have exceeded your application’s rate limit or the API is currently receiving a high volume of requests.
Headers
Name |
Description |
X-Correlation-ID |
String
The X-Correlation-ID from the request header, if supplied, mirrored back.
Example: 11C46F5F-CDEF-4865-94B2-0EE0EDCC26DA
|
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."
} ]
}
object
|
|
resourceType
string
|
Default: OperationOutcome
|
issue
array
|
List of issues that have occurred.
Min items: 1
|
object
|
|
severity
string
required
|
Allowed values: fatal, error, warning, information
|
code
string
required
|
Allowed values: expired, forbidden, invalid, processing, security, throttled
|
diagnostics
string
|
Additional diagnostic information about the issue.
Example: Not specified
|
expression
array
|
FHIRPath of element(s) related to the error.
|
string
|
Example: requester.identifier
|