Skip to main content
Back to Overview Back to Home

Notifications API

The Notifications API provides a way of fetching updates about multiple applications submitted by the same business unit. Currently, this service only supports a pull interaction model, where notifications must be requested periodically. However, more information about a push interaction model will be shared in future.

This API has two endpoints:

  • GET /v1/notifications - get all unacknowledged notifications
  • POST /v1/notifications/acknowledge - notify HM Land Registry the notifications have been received

Receive notifications

The GET request to fetch all notifications takes the following URL query parameters (which are optional):

  • created_after - only retrieve notifications with a created_timestamp after this date
  • created_before - only retrieve notifications with a created_timestamp before this date
  • status - only retrieve notifications with a specific status, either NEW or ACKNOWLEDGED
  • occured_after - only retrieve notifications with a event_timestamp after this date
  • occured_before - only retrieve notifications with a event_timestamp before this date
  • notification_type - only retrieve notifications with the specific notification_type
  • subject - only retrieve notifications with the specific subject
  • additional_provider_filter - only retrieve notifications that match the provided additional_provider_filter

Notification delivery is ‘at least once’, meaning a specific event at a specific time may result in one or more notifications (i.e. duplicate notifications for the same event). Duplicate events will have the same source_datetime field and application_status field, which can be used to locate and ignore duplicates when receiving notifications. Notifications will continue to be returned by the endpoint until they are acknowledged.

Currently, only a few notification payload types are supported:

  • When an application becomes accepted - application_status: ACCEPTED
  • When an application is not accepted or not created - application_status: SYSTEM_ERROR or application_status: REJECTED
  • When an application has passed validation, but has not been added to the day list (out of hours) - application_status: VALIDATED

For more information about statuses, see the Application information API. Additional notifications to be added at a later date include:

  • when a validated application is accepted
  • any progress of an application after it has been added to the day list (Completion, Rejection etc.). The HM Land Registry portal service should be used until the API supports this behavior

API Specification

See the API Specification here

Acknowledge notifications

Once a notification has been processed by your system, the notification should be acknowledged. To do this, send a list of notification_ids to the Acknowledge notifications API as a POST request. This will change the status of those notifications to ACKNOWLEDGED.

API Specification

See the API Specification here

Diagrams

Examples

ACCEPTED notification

{
   "data": [{
       "notification_id": "1bg5f407-8096-40d1-87bg-9a2a103ebg85",
       "created_datetime": "2024-11-04T08:25:15.575Z",
       "event_datetime": "2024-11-04T08:12:38.377Z",
       "payload_schema": "https://landregistry/schema/bg-application-notification-payload/1.0",
       "notification_type": "application.applicationcreation.initiated",
       "subject_type": "application",
       "subject": "13bg5f07-3096-40d2-87bg-2a2a325ebg96",
       "status": "NEW",
       "additional_provider_filter": "subUnit1",
       "payload": {
           "hmlr_reference": "123456A",
           "type": "STATUS_CHANGED",
           "application_status": "ACCEPTED",
           "priority": "2024-09-20T09:56:46"
       }
    }],
    "links": {
        "self": "/v1/notifications?created_after=2024-11-04T08:25:15.575Z",
        "next": "/v1/notifications?created_after=2024-11-04T08:25:15.575Z"
    }
}

REJECTED notification

{
   "data": [{
       "notification_id": "1bg5f407-8096-40d1-87bg-9a2a103ebg85",
       "created_datetime": "2024-11-04T08:25:15.575Z",
       "event_datetime": "2024-11-04T08:12:38.377Z",
       "payload_schema": "https://landregistry/schema/bg-application-notification-payload/1.0",
       "notification_type": "application.applicationcreation.initiated",
       "subject_type": "application",
       "subject": "13bg5f07-3096-40d2-87bg-2a2a325ebg96",
       "status": "NEW",
       "additional_provider_filter": "subUnit1",
       "payload": {
           "type": "STATUS_CHANGED",
           "application_status": "REJECTED"
       }
    }],
    "links": {
        "self": "/v1/notifications?created_after=2024-11-04T08:25:15.575Z",
        "next": "/v1/notifications?created_after=2024-11-04T08:25:15.575Z"
    }
}

Notifications for multiple applications

{
   "data": [{
       "notification_id": "1bg5f407-8096-40d1-87bg-9a2a103ebg85",
       "created_datetime": "2024-11-04T08:25:15.575Z",
       "event_datetime": "2024-11-04T08:12:38.377Z",
       "payload_schema": "https://landregistry/schema/bg-application-notification-payload/1.0",
       "notification_type": "application.applicationcreation.initiated",
       "subject_type": "application",
       "subject": "13bg5f07-3096-40d2-87bg-2a2a325ebg96",
       "status": "NEW",
       "additional_provider_filter": "subUnit1",
       "payload": {
           "type": "STATUS_CHANGED",
           "application_status": "REJECTED"
       }
    }, {
       "notification_id": "19b8951b-afd2-4c2f-84a8-15266b5604ae",
       "created_datetime": "2024-11-05T10:25:15.575Z",
       "event_datetime": "2024-11-05T10:12:38.377Z",
       "payload_schema": "https://landregistry/schema/bg-application-notification-payload/1.0",
       "notification_type": "application.applicationcreation.initiated",
       "subject_type": "application",
       "subject": "2f23f6f3-b2b7-4d00-86e9-7fadcce3a763",
       "status": "NEW",
       "additional_provider_filter": "subUnit2",
       "payload": {
           "type": "STATUS_CHANGED",
           "application_status": "VALIDATED"
       }
    }],
    "links": {
        "self": "/v1/notifications?created_after=2024-11-04T08:25:15.575Z",
        "next": "/v1/notifications?created_after=2024-11-05T10:25:15.575Z"
    }
}

See more