You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: docs/collections/_consumers/integration.md
+256-1Lines changed: 256 additions & 1 deletion
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -5,4 +5,259 @@ has_children: false
5
5
has_toc: false
6
6
---
7
7
8
-
[[Placeholder for Integration Guide]]
8
+
## About this guide
9
+
10
+
This guide helps approved letter suppliers to integrate with the NHS Notify Supplier API.
11
+
The API lets you to:
12
+
13
+
- get lists of letters allocated to you
14
+
- download letter PDFs and metadata
15
+
- update and manage letter statuses
16
+
- submit and retrieve management information (MI)
17
+
18
+
The aim of this guide is to help you move smoothly from onboarding to live operation.
19
+
It explains what you need to do, what we’ll do, and where to get support.
20
+
21
+
You have 90 calendar days to complete onboarding activities and submit all required evidence of conformity. During this period, the NHS Notify API development team will provide integration support through two one-week integration test windows to help ensure a successful connection and validation against the Supplier API.
22
+
23
+
### Scope of the document
24
+
25
+
- Pre-onboarding and Conformance
26
+
- How the API works
27
+
- Prepare your integration
28
+
- Build your integration
29
+
- Complete integration testing
30
+
- Specification proofing before going live
31
+
- Apply to go live
32
+
- Go live
33
+
- Support
34
+
35
+
---
36
+
37
+
## Pre-onboarding & Conformance
38
+
39
+
Before you can begin technical onboarding, your organisation must:
40
+
41
+
- be an approved NHS letter supplier under the [framework agreement](https://www.crowncommercial.gov.uk/agreements/RM6389)
42
+
- nominate your technical and operational contacts
43
+
44
+
Once these steps are completed, you can start preparing your integration.
45
+
46
+
---
47
+
48
+
## How the API works
49
+
50
+
The **NHS Notify Supplier API** connects your print production systems to NHS Notify so you can securely receive, print, and report on letters.
When a letter is created in NHS Notify, it’s stored securely as a PDF and allocated to a supplier.
57
+
This triggers an event to make the letter available for you to retrieve.
58
+
59
+
### List of letters and downloads
60
+
61
+
Retrieve a list of all available letters, including key details such as the letter ID and current status.
62
+
The list only contains the summary information - not the actual PDF files.
63
+
To access each full letter, download the PDF directly by making a request to the `/letters/{id}/data` endpoint.
64
+
This will redirect to a short-lived URL to download the file.
65
+
These links are temporary and expire after about one minute, so downloads should be completed right away or re-requested if the link has expired.
66
+
67
+
### API access
68
+
69
+
All supplier requests go through NHS API Management (APIM), which handles authentication.
70
+
71
+
### Main endpoints
72
+
73
+
You will use the API to:
74
+
75
+
- Retrieve letter lists and PDFs
76
+
- Acknowledge receipt
77
+
- Update letter statuses
78
+
- Submit and validate Management Information (MI)
79
+
80
+
### Event processing and data flow
81
+
82
+
The API is event-driven. You will need to poll the letters that are allocated to you.
83
+
84
+
### Letter Status
85
+
86
+
Each letter moves through a defined set of statuses that describe its journey from allocation to final outcome.
87
+
These statuses provide visibility of where a letter is in its lifecycle - from being assigned to your organisation, through printing and dispatch, to successful delivery or failure.
88
+
89
+
You are required to update each letter's status through the API as key processing events occur.
90
+
The status updates need to be as close to real time as possible.
91
+
This enables NHS Notify to monitor performance, confirm postal outcomes, and ensure accurate tracking across the Service.
92
+
State transitions are not currently enforced. Technically, stages can be skipped or reversed. However, reverting an ACCEPTED letter to PENDING or marking a DISPATCHED letter as FAILED is not expected behaviour.
93
+
94
+
Statuses are categorised as follows:
95
+
96
+
**Core statuses** - mandatory updates that represent the key points of a letter’s lifecycle.
-**ACCEPTED:** The letter has passed validation checks and is ready for production.
100
+
-**REJECTED:** The letter is malformed - for example, the letter ID is not recognised or the associated PDF is missing.
101
+
-**FORWARDED:** The letter requires re-direction to a specialist supplier (e.g. RNIB or another accessible-format partner).
102
+
-**DISPATCHED:** The letter has been handed over to a postal service.
103
+
-**FAILED:** An unrecoverable error occurred during production, preventing the letter from being dispatched.
104
+
-**RETURNED:** The letter was undeliverable and has been returned to sender.
105
+
-**CANCELLED:** The letter was cancelled following a request from the NHS Notify team
106
+
107
+
**Optional statuses** - additional, non-mandatory updates that can provide greater operational insight.
108
+
The optional statuses are: **PRINTED**, **ENCLOSED**, **DELIVERED**, and **DESTROYED**.
109
+
These can be used if your internal workflow supports more granular reporting.
110
+
111
+
-**PRINTED:** The letter has been printed.
112
+
-**ENCLOSED:** The printed letter and any relevant enclosures have been inserted into the mailing envelope.
113
+
-**DELIVERED:** The letter has been delivered to the patient
114
+
115
+
Refer to the Letter Status Lifecycle diagram below for the complete sequence of possible transitions, including optional supplier-initiated updates and NHS Notify system-driven outcomes.
You must prepare your integration before you can get access to the NHS Notify integration environment.
124
+
You’ll need technical or developer support to complete tasks in this step.
125
+
126
+
### To set up your APIM application
127
+
128
+
1.[Sign in to your NHS Digital developer account](https://digital.nhs.uk/developer)
129
+
2. Create an APIM application
130
+
3. Select **integration test** as the environment
131
+
4. Choose **NHS Notify Supplier API (integration environment)** as the connected API
132
+
133
+
You need to inform us by email at [[email protected]](mailto:[email protected]) with your APIM Application ID so we can register you to the INT environment.
134
+
135
+
Once your APIM application has been created and registered, you’ll be granted access to the NHS Notify integration environment. With your technical setup complete and credentials in place, you can now begin building and testing your connection with the NHS Notify Supplier API in a controlled integration setting.
136
+
137
+
---
138
+
139
+
## Build your integration
140
+
141
+
Once you have access to the integration environment, you can begin building and testing your connection with the NHS Notify Supplier API.
142
+
143
+
How you build your integration to meet your needs is your responsibility.
144
+
145
+
### API specification
146
+
147
+
The API is defined using the [OpenAPI Specification (OAS)](https://spec.openapis.org/oas/latest.html) format.
148
+
149
+
You can find it on [GitHub](https://github.com/NHSDigital/nhs-notify-supplier-api/tree/main/specification/api) and on the [NHS England Developer Catalogue](https://digital.nhs.uk/developer/api-catalogue/Alphabet/N).
150
+
151
+
A Postman collection will also be available in [GitHub](https://github.com/NHSDigital/nhs-notify-supplier-api/tree/main/postman) to explore the requests within the API.
152
+
153
+
### Version control
154
+
155
+
We may make additive non-breaking changes to the API without notice, for example the addition of fields to a response or new optional fields to a request.
156
+
157
+
### Developer tools and sandbox
158
+
159
+
To help you get started, we provide a sandbox environment and developer tools to speed up your development.
160
+
161
+
#### Sandbox
162
+
163
+
A safe environment that mirrors the live API using synthetic data.
164
+
You can test end-to-end workflows without using real patient data.
165
+
166
+
- Access via APIM: <https://sandbox.api.service.nhs.uk/notify-supplier>
- Providing you with two one-week testing windows for your integration.
195
+
- Configuring and maintaining the INT environment.
196
+
- Seeding the environment with test data.
197
+
- Reviewing your submitted evidence and confirming readiness for production
198
+
199
+
---
200
+
201
+
## Specification proofing before going live
202
+
203
+
Before your service can move into live operation, you must provide proof samples of your letter outputs to demonstrate that they meet the NHS Notify design and production standards.
204
+
205
+
You’ll need to submit both digital proofs (for content and layout verification) and physical printed samples (for print quality, formatting, and envelope presentation). These proofs will be reviewed by the NHS Notify supplier team to ensure accuracy, consistency, and compliance with the approved specifications.
206
+
207
+
Only once your proofs have been reviewed and approved will you receive confirmation that your system and outputs are ready to move forward into the live (production) environment.
208
+
209
+
Digital proof will need to be sent via e-mail using this address: <[email protected]> and physical proof will need to be sent to: Mr Wayne Shirt (NHS Notify), 6th Floor, 7 & 8 Wellington Place, Leeds, West Yorkshire, LS1 4AP.
210
+
211
+
---
212
+
213
+
## Apply to go live
214
+
215
+
Before going live you'll need to be successful in securing a call off contract.
216
+
217
+
Once this is signed and you are ready to go live, please inform your supplier manager by writing an email to <[email protected]>
218
+
219
+
To prepare for go live, **you (the Supplier)** must provide your production (PROD) application name and Application ID from APIM.
220
+
221
+
### Smoke test
222
+
223
+
Before we can confirm your go-live, you will run a short smoke test in the production environment with support from the NHS Notify Supplier API team.
224
+
This checks that your live credentials, connectivity, and print workflow all function correctly end-to-end.
225
+
226
+
During the smoke test you (the Supplier) will:
227
+
228
+
1. Retrieve and print one or more live letters through the production API.
229
+
2. Send the output of the specifications to the address provided.
230
+
3. Confirm reporting - submit a Management Information (MI) update for the smoke-test letter and verify that it’s recorded successfully in NHS Notify
231
+
232
+
**We (NHS Notify) will:**
233
+
234
+
- Configure your access to the production environment.
235
+
- Review the smoke-test results and confirm your output meets NHS Notify print specifications
236
+
237
+
---
238
+
239
+
## Go live
240
+
241
+
On your agreed go-live date, you should make live requests to the NHS Notify Supplier API to receive letters for printing.
242
+
243
+
### After go live, the NHS Notify team will
244
+
245
+
- Run early service support calls to help monitor your integration and ensure everything is working as expected.
246
+
- Monitor performance and delivery metrics.
247
+
- Provide help through the [NHS Notify Support](https://notify.nhs.uk/support/) portal
248
+
249
+
If you find a problem or have a question, contact the **Supplier API team** by writing an email to [[email protected]](mailto:[email protected]).
250
+
251
+
---
252
+
253
+
## Support
254
+
255
+
### Raising issues and questions
256
+
257
+
If you encounter a bug, unexpected behaviour or have a question about the API, please contact the NHS Notify Supplier API Team at [[email protected]](mailto:[email protected]).
258
+
259
+
When reporting issues, include as much evidence as possible - such as logs, request/response IDs and timestamps - to help us investigate promptly.
260
+
261
+
### Knowledge sharing
262
+
263
+
A [Q&A page](https://nhsd-confluence.digital.nhs.uk/spaces/RIS/pages/1187359717/Letter+Supplier+API+-+Q+A) is available for common questions. Please check this page before raising a new query.
0 commit comments