GOV.UK Notify has a public API. The API allows government services to use GOV.UK Notify, to send notifications and to get information on the progress of those notifications.
During our private beta, we've done extensive user research with service teams and learned more about what functionality the API should provide. We've incorporated these changes into a new, version 2, of the API.
We want to release this version before moving to public beta.
If you’re new to GOV.UK Notify and would like to try out the service, then go to GOV.UK Notify and create an account.
If you’ve already integrated with the API and are using one of our client libraries, you can take advantage of the new API by upgrading to the latest version of the client library.
What’s new in the updated API
The responses are now more concise and focused on information service teams need.
The error response formats have been updated and are now more informative and easier to understand. They include the error name, status code and error message. This will help link error messages to the documentation.
When using the ‘get all notifications’ function, you can choose from several new filters: notification status, type, reference, and 'older than' ID.
There’s a new input parameter for sending an email or SMS - ‘reference’ is an optional unique identifier for a notification or a batch of notifications. This allows service teams to use their own identifiers when interacting with GOV.UK Notify.
Pagination has been improved with the addition of the ‘older than’ ID filter to get the next page of notifications. This ensures the pagination urls are more consistent - previously the data on each page could change as more notifications were added to the data set.
You can also filter the notifications by status and type.
Full details of all these interactions are available in the READMEs for the client libraries.
We’ve updated our client libraries
All our client libraries have been updated to use version 2 of the GOV.UK Notify API. These are available to use now.
Older versions of the libraries are still available. However, the latest client libraries won't be backwards-compatible because of updates to the API responses.
Upgrading to the latest version of the client libraries will take a small amount of work to make sure they integrate correctly with your service. The CHANGEME file in the client library details the changes.
Below is a list of available client libraries. The README file for each client library has been updated to describe the changes in the newly released APIs:
Managing the versions
Making changes to our API is not something we take lightly. We'll maintain the old API version while we help migrate all existing client libraries across.
We recommended new users start with the latest client libraries.
To ensure a smooth transition, we'll monitor the use of the now deprecated version of the API, and we'll liaise with service teams to support their migrations.
If you have a question, ask the team using the feedback page.
You can sign up for email alerts to future GOV.UK Notify blog posts.
GDS is expanding, and we have a number of positions that need to be filled - especially on the Government as a Platform team. So we’re always on the lookout for talented people. Have a look at our videos describing how we work, our vacancies page, or drop us a line.