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 /v0/notifications - get all notifications that match the provided filters
POST /v0/notifications/acknowledge - notify HM Land Registry the notifications have been received

This API can be used to get more information after receiving a notification indicating the application has changed. For information about which notifications will be available, visit the notifications section of the Submit an application service API page.

View the API Specification

See the API Specification here

How the service API works

How to test this service API

HMLR does not currently provide a test environment for integrators using our Business Gateway APIs. Instead, we’ve provided example code to demonstrate what you should expect to see when developing your own services.

This information is coming soon.

Technical guide

How to use the Notifications service API

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
limit - the maximum number of notifications to return in a single response

Only notifications for the business unit of the user making the request will be returned.

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 event_datetime field and notification_type, 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.

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.

Validation rules

There are no validation rules for implementing this service API.

Example requests and responses

For specific examples of notification payloads produced during application submission, see submit an application notifications

Get notifications request

GET /v0/notifications?created_after=2025-01-01T00:00:00 HTTP/1.1

Get notifications response

{
  "data": [
    {
      "notification_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "created_datetime": "2025-03-06T14:32:55.295Z",
      "event_datetime": "2025-03-06T14:32:55.295Z",
      "payload_schema": "https://example.com/",
      "notification_type": "string",
      "subject_type": "string",
      "subject": "string",
      "additional_provider_filter": "string",
      "status": "NEW",
      "payload": {
        "additionalProp1": {},
        "additionalProp2": {},
        "additionalProp3": {}
      }
    }
  ]
}

Acknowledge notifications request

POST /v0/notifications/acknowledge HTTP/1.1

{
  "data": [
    "3fa85f64-5717-4562-b3fc-2c963f66afa6"
  ]
}

Acknowledge notifications response

{
  "data": {
    "acknowledged": [
      "3fa85f64-5717-4562-b3fc-2c963f66afa6"
    ]
  }
}

Test Stubs

Base URL: https://bgtest.landregistry.gov.uk/bg2test/api

1. Get All Notifications

Request

Method: GET

Endpoint: /v0/notifications

Headers:

Authorization: <any-value>

Response

Status: 200

Body:

{
  "data": [
    {
      "notification_id": "{{ID}}",
      "created_datetime": "2024-01-01T12:00:00.000",
      "event_datetime": "2024-01-01T12:00:00.000",
      "payload_schema": "https://landregistry.github.io/bgtechdoc/vcad/schemas/v1/accepted-priority-protected.json",
      "notification_type": "APPLICATION_ACCEPTED_ON_DAY_LIST",
      "subject_type": "LAND_REGISTER_APPLICATION",
      "subject": "b3ac19be-2b6d-4b8a-971c-e758b0e8e790",
      "additional_provider_filter": "subUnit1",
      "status": "ACKNOWLEDGED",
      "payload": {
        "data": {
          "hmlr_reference": "ABC456A",
          "status": "ACCEPTED",
          "priority": "2024-09-20T09:56:46"
        }
      }
    },
    {
      "notification_id": "{{ID}}",
      "created_datetime": "2024-01-01T12:00:00.000",
      "event_datetime": "2024-01-01T12:00:00.000",
      "payload_schema": "https://landregistry.github.io/bgtechdoc/vcad/schemas/v1/accepted-priority-protected.json",
      "notification_type": "APPLICATION_ACCEPTED_ON_DAY_LIST",
      "subject_type": "LAND_REGISTER_APPLICATION",
      "subject": "2563940e-ae95-4e7e-9b33-49a6571abdf6",
      "additional_provider_filter": "subUnit1",
      "status": "NEW",
      "payload": {
        "data": {
          "hmlr_reference": "ABC456B",
          "status": "ACCEPTED",
          "priority": "2024-09-20T09:56:46"
        }
      }
    },
    {
      "notification_id": "{{ID}}",
      "created_datetime": "2024-01-01T12:00:00.000",
      "event_datetime": "2024-01-01T12:00:00.000",
      "payload_schema": "https://landregistry.github.io/bgtechdoc/vcad/schemas/v1/validation-failed.json",
      "notification_type": "APPLICATION_VALIDATION_FAILED",
      "subject_type": "LAND_REGISTER_APPLICATION",
      "subject": "3be62ad3-c542-452d-975e-6cd18d77196f",
      "additional_provider_filter": "subUnit1",
      "status": "NEW",
      "payload": {
        "data": {
          "status": "VALIDATION_FAILED"
        }
      }
    }
  ]
}

2. Get All New Notifications

Request

Method: GET

Endpoint: /v0/notifications?status=NEW

Headers:

Authorization: <any-value>

Response

Status: 200

Body:

{
  "data": [
    {
      "notification_id": "{{ID}}",
      "created_datetime": "2024-01-01T12:00:00.000",
      "event_datetime": "2024-01-01T12:00:00.000",
      "payload_schema": "https://landregistry.github.io/bgtechdoc/vcad/schemas/v1/accepted-priority-protected.json",
      "notification_type": "APPLICATION_ACCEPTED_ON_DAY_LIST",
      "subject_type": "LAND_REGISTER_APPLICATION",
      "subject": "2563940e-ae95-4e7e-9b33-49a6571abdf6",
      "additional_provider_filter": "subUnit1",
      "status": "NEW",
      "payload": {
        "data": {
          "hmlr_reference": "ABC456B",
          "status": "ACCEPTED",
          "priority": "2024-09-20T09:56:46"
        }
      }
    },
    {
      "notification_id": "{{ID}}",
      "created_datetime": "2024-01-01T12:00:00.000",
      "event_datetime": "2024-01-01T12:00:00.000",
      "payload_schema": "https://landregistry.github.io/bgtechdoc/vcad/schemas/v1/validation-failed.json",
      "notification_type": "APPLICATION_VALIDATION_FAILED",
      "subject_type": "LAND_REGISTER_APPLICATION",
      "subject": "3be62ad3-c542-452d-975e-6cd18d77196f",
      "additional_provider_filter": "subUnit1",
      "status": "NEW",
      "payload": {
        "data": {
          "status": "VALIDATION_FAILED"
        }
      }
    }
  ]
}

3. Get All Acknowledged Notifications

Request

Method: GET

Endpoint: /v0/notifications?status=ACKNOWLEDGED

Headers:

Authorization: <any-value>

Response

Status: 200

Body:

{
  "data": [
    {
      "notification_id": "{{ID}}",
      "created_datetime": "2024-01-01T12:00:00.000",
      "event_datetime": "2024-01-01T12:00:00.000",
      "payload_schema": "https://landregistry.github.io/bgtechdoc/vcad/schemas/v1/accepted-priority-protected.json",
      "notification_type": "APPLICATION_ACCEPTED_ON_DAY_LIST",
      "subject_type": "LAND_REGISTER_APPLICATION",
      "subject": "b3ac19be-2b6d-4b8a-971c-e758b0e8e790",
      "additional_provider_filter": "subUnit1",
      "status": "ACKNOWLEDGED",
      "payload": {
        "data": {
          "hmlr_reference": "ABC456A",
          "status": "ACCEPTED",
          "priority": "2024-09-20T09:56:46"
        }
      }
    }
  ]
}

4. Get All with Invalid Date Filter

Request

Method: GET

Endpoint: /v0/notifications?created_after=2020-01-01T00:00:00&created_before=2015-01-01T00:00:00

Headers:

Authorization: <any-value>

Response

Status: 400

Body:

{
  "type": "https://problems-registry.smartbear.com/bad-request/",
  "title": "Bad Request",
  "status": 400,
  "detail": "created_after parameter cannot be after created_before parameter",
  "instance": "/v0/notifications",
  "code": "400-01"
}

5. Acknowledge Notifications

Request

Method: POST

Endpoint: /v0/notifications/acknowledge

Headers:

Authorization: <any-value>

Body:

{
  "data": [
    "b3ac19be-2b6d-4b8a-971c-e758b0e8e790",
    "87654321-2b6d-4b8a-971c-e758b0e8e790",
    "12345678-2b6d-4b8a-971c-e758b0e8e790"
  ]
}

Response

Status: 200

Body:

{
  "data": {
    "acknowledged": [
      "b3ac19be-2b6d-4b8a-971c-e758b0e8e790"
    ],
    "not_found": [
      "87654321-2b6d-4b8a-971c-e758b0e8e790",
      "12345678-2b6d-4b8a-971c-e758b0e8e790"
    ]
  }
}

6. Application Queued Notification

Request

Method: GET

Endpoint: /v0/notifications?notification_type=APPLICATION_ACCEPTED_QUEUED_FOR_DAY_LIST

Headers:

Authorization: <any-value>

Response

Status: 200

Body:

{
  "data": [{
    "notification_id": "{{ID}}",
    "created_datetime": "2024-01-01T12:00:00.000",
    "event_datetime": "2024-01-01T12:00:00.000",
    "payload_schema": "https://landregistry.github.io/bgtechdoc/vcad/schemas/v1/accepted-awaiting-priority.json",
    "notification_type": "APPLICATION_ACCEPTED_QUEUED_FOR_DAY_LIST",
    "subject_type": "LAND_REGISTER_APPLICATION",
    "subject": "45454545-2b6d-4b8a-971c-e758b0e8e790",
    "additional_provider_filter": "subUnit1",
    "status": "NEW",
    "payload": {
      "data" : {
        "status": "ACCEPTED_AWAITING_PRIORITY"
      }
    }
  }]
}

7. System Error Notification

Request

Method: GET

Endpoint: /v0/notifications?notification_type=SYSTEM_ERROR

Headers:

Authorization: <any-value>

Response

Status: 200

Body:

{
  "data": [{
    "notification_id": "{{ID}}",
    "created_datetime": "2024-01-01T12:00:00.000",
    "event_datetime": "2024-01-01T12:00:00.000",
    "payload_schema": "https://landregistry.github.io/bgtechdoc/vcad/schemas/v1/system-error.json",
    "notification_type": "SYSTEM_ERROR",
    "subject_type": "LAND_REGISTER_APPLICATION",
    "subject": "45454545-2b6d-4b8a-971c-e758b0e8e790",
    "additional_provider_filter": "subUnit1",
    "status": "NEW",
    "payload": {
      "data" : {
        "status": "SYSTEM_ERROR"
      }
    }
  }]
}

8. Application Cancelled Notification

Request

Method: GET

Endpoint: /v0/notifications?notification_type=APPLICATION_CANCELLED

Headers:

Authorization: <any-value>

Response

Status: 200

Body:

{
  "data": [{
    "notification_id": "{{ID}}",
    "created_datetime": "2024-01-01T12:00:00.000",
    "event_datetime": "2024-01-01T12:00:00.000",
    "payload_schema": "https://landregistry.github.io/bgtechdoc/vcad/schemas/v1/application-cancelled.json",
    "notification_type": "APPLICATION_CANCELLED",
    "subject_type": "LAND_REGISTER_APPLICATION",
    "subject": "45454545-2b6d-4b8a-971c-e758b0e8e790",
    "additional_provider_filter": "subUnit1",
    "status": "NEW",
    "payload": {
      "data" : {
        "status": "CANCELLED"
      }
    }
  }]
}

9. Application Completed Notification

Request

Method: GET

Endpoint: /v0/notifications?notification_type=APPLICATION_COMPLETED

Headers:

Authorization: <any-value>

Response

Status: 200

Body:

{
  "data": [{
    "notification_id": "{{ID}}",
    "created_datetime": "2024-01-01T12:00:00.000",
    "event_datetime": "2024-01-01T12:00:00.000",
    "payload_schema": "https://landregistry.github.io/bgtechdoc/vcad/schemas/v1/application-completed.json",
    "notification_type": "APPLICATION_COMPLETED",
    "subject_type": "LAND_REGISTER_APPLICATION",
    "subject": "45454545-2b6d-4b8a-971c-e758b0e8e790",
    "additional_provider_filter": "subUnit1",
    "status": "NEW",
    "payload": {
      "data" : {
        "status": "COMPLETED"
      }
    }
  }]
}

Notifications API

View the API Specification

How the service API works

How to test this service API

Technical guide

How to use the Notifications service API

Receive notifications

Acknowledge notifications

Validation rules

Example requests and responses

Get notifications request

Get notifications response

Acknowledge notifications request

Acknowledge notifications response

Test Stubs

1. Get All Notifications

Request

Response

2. Get All New Notifications

Request

Response

3. Get All Acknowledged Notifications

Request

Response

4. Get All with Invalid Date Filter

Request

Response

5. Acknowledge Notifications

Request

Response

6. Application Queued Notification

Request

Response

7. System Error Notification

Request

Response

8. Application Cancelled Notification

Request

Response

9. Application Completed Notification

Request

Response

See more