CDS API Approach Document

HMRC are planning an update to the Pull Notification API in Trade Test. The implementation is currently planned for the morning of the 7th November Thursday by 8.30am

This will not require any downtime to the service.

 The updated version of the API Approach document, previously shared in March, includes the 3 planned additional endpoints to the Pull Notification API.

A summary of the planned changes has been included below and will be released on the Dev Hub once the implementation is complete.

New endpoints

You can now get notification identifiers for a given conversation identifier by using one of these three endpoints:

  • GET /notifications/conversationId/{conversationId}
    Get a list of notification identifiers for the given conversation identifier
  • GET /notifications/conversationId/{conversationId}/unpulled
    Get a list of unpulled notification identifiers for the given conversation identifier
  • GET /notifications/conversationId/{conversationId}/pulled
    Get a list of pulled notification identifiers for the given conversation identifier

These endpoints will help developers manage the retrieval of notifications on a more granular basis.Up until now, you have been able to get all pulled or unpulled notifications for your registered application.

Now you can check the notifications for a specific conversation identifier, then choose to get some or all of these notifications. This should help with diagnosing any issues you may have with retrieval of notifications.

The existing Pull Notifications API endpoints remain available and unchanged.

Deprecated endpoints

We have deprecated these 2 endpoints:

  • GET /notifications
  • DELETE /notifications/{id}

These endpoints will function as normal until they are removed in a future release. These endpoints are being deprecated because we found developers were deleting notifications, then needing to get them again. For this reason, we moved to have the unpulled and pulled notification queues.

HMRC do not recommend using these two endpoints.

Recommended usage pattern

You can get all of the notifications for your application or you can get them for a given conversation identifier. We recommend getting them by conversation, as follows:

  1. Get a list of unpulled notification identifiers for a given conversation by calling GET /notifications/conversationId/{conversationId}/unpulled
  2. Iterate over this list of notification identifiers and get each unpulled notification from the unpulled queue by calling GET /notifications/unpulled/{notificationId}. When you get a notification from the unpulled queue it will move to the pulled queue.
  3. To get a notification again after you have retrieved it, get it from the pulled queue by calling GET /notifications/pulled/{notificationId}

Back to news

We use cookies on this site to improve your experience. By continuing to browse the site you are agreeing to our use of cookies. You will only see this message once. Find out more

close