A guide to notifications

How to monitor updates to your applications, using the Notifications API

Overview

A new notification is published every time there is a status or event update to a submitted application. The Notifications API allows you to retrieve and filter these notifications for all applications from your business unit, and then either:

• process and write the relevant updates to your system. For example, when a transaction has completed
• take appropriate action using another API. For example, when there is a validation error, you can send a request to the Application information API to find out the specific error text

This guide:

• provides a workflow for retrieving, filtering, processing, and acknowledging notifications
• explains limitations of the Notifications API

Retrieve, filter, process, and acknowledge notifications

To monitor the progress of your business unit’s submitted applications, you need to continuously retrieve, process, and acknowledge notifications. The following steps describe a standard workflow, with different strategies for filtering notifications.

Step 1: Retrieve and filter notifications

You can choose whether to retrieve all available notifications and filter the responses yourself, or use the notification query parameters to limit the number of notifications.

To retrieve all available notifications and filter the responses yourself, send a request to the GET /notifications endpoint:

• with an additional_provider_filter value (GET /v1/notifications?additional_provider_filter=mycompanyid) if you specify this value when submitting applications
• with no query parameters (GET /v1/notifications) if you do not use the additional_provider_filter

To limit the number of notifications retrieved, send a request to the GET notifications endpoint including notification query parameters, which act as filters. For example, use:

• the created_after date parameter to limit the responses to a particular time period (GET /v1/notifications?created_after=2026-08-24t00:00:00 http1:1)
• the subject query parameter to retrieve only notifications for a particular application (GET /v1/notifications?subject=3bac33ba-b20a-4525-be59-e5d820b36a14)

Requests will retrieve a maximum of 100 matching notifications published in the last 30 days, sorted by age (oldest first).

See the Notifications API documentation for example requests and responses.

Step 2: Process notifications

When you have retrieved a batch of notifications, you need to process them. You can use the notification_type value to identify which notifications:

• contain new information, such as an updated application status, or related information, which you can use to update your system
• mean you need take further action using a related API

The following table describes each notification type and suggested actions to take.

Notification type	Description	Action
application.accepted-priority-protected	Application accepted and added to the daylist	Use the Application information API to check for errors or warnings associated with the application.
application.accepted-priority-pending	Application accepted and queuing for the daylist	Wait for further notifications with application status updates.
application.validation-failed	Application failed validation	Use the Application information API to check for validation errors associated with the application.
application.error	Application not added to the daylist due to a system error	A processing failure has occurred. Try resubmitting the application. If the error persists, contact HMLR support
application.correspondence-despatched	Correspondence was raised on the application	Use the Download a document API to download the correspondence documents.
application.attachment-success	Document successfully attached to application	Wait for further notifications with application status updates.
application.attachment-failed	Document failed to attach to application	Review the error details, fix the issue and try attaching the document again.
application.message-success	Message successfully attached to application	Wait for further notifications with application status updates.
application.message-failed	Message failed to attach to application	Review the error details, fix the issue and try attaching the message again.
application.cancelled	Application cancelled	If any correspondence documents have been created, use the Download a document API to download them.
application.completed	Application completed	Use the Download a document API to download the correspondence documents. You can also use the Application information API to get full completion details for the application.

See the Notifications API documentation for schemas that show the data structure for each notification type.

Step 3: Acknowledge notifications

When you have finished processing a batch of notifications, you need to acknowledge them. To do this, send a POST request to the Acknowledge notifications endpoint (/v1/notifications/acknowledge) including the ID of each notification. You can acknowledge a maximum of 100 notifications in each request.

A successful request updates the status of each notification to ACKNOWLEDGED, which will exclude these notifications from subsequent GET requests, unless you specifically request them using the status query parameter.

See the Notifications API documentation for example requests and responses.

Limitations

Before you start to integrate with the Notifications API, make sure you consider the following limitations:

• notifications are only retained for 30 days after publication
• you can only retrieve the oldest 100 unacknowledged notifications in a single batch
• you can only acknowledge 100 notifications in a single batch

These limitations will affect the frequency with which you need to repeat the workflow. For example, if you are processing:

• small numbers of applications each day (less than 50), consider repeating the workflow once or twice each day
• larger numbers of applications, try repeating the workflow up to every hour