Skip to main content
Back

Notifications API technical guide

Use this service to get updates about multiple applications submitted by the same business unit

Version and Status

How to use the Notifications 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. NEW is the default if status is not specified.
  • occurred_after - only retrieve notifications with an event_timestamp after this date
  • occurred_before - only retrieve notifications with an event_timestamp before this date
  • notification_type - only retrieve notifications with the specific notification_type
  • subject_type - only retrieve notifications with the specific subject_type. The only subject_type currently available is APPLICATION.
  • subject - only retrieve notifications for a specific application, using the application_request_id of the application as the subject value
  • 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

A maximum of 100 matching notifications will be returned, sorted by age (oldest first).

A GET request with no parameters will return the 100 oldest notifications. To obtain newer notifications, use the created_after or occurred_after parameters.

Only notifications related to applications submitted by your business unit and matching the additional_provider_filter requested will be returned. If no additional_provider_filter parameter is specified, only applications that were submitted with no additional_provider_filter are returned.

Notification delivery is ‘at least once’, meaning a specific event at a specific time may result in one or more notifications (i.e. multiple notifications for the same event, but with different IDs).

Duplicate notifications 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, so each duplicate notification still needs to be acknowledged separately.

All notifications are deleted after a month, whether acknowledged or not.

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 endpoint (POST /v1/notifications/acknowledge) of the notifications API as a POST request. This will change the status of those notifications to ACKNOWLEDGED.

Subsequent GET calls won’t include acknowledged notifications by default.

Notification types

Notifications are the most effective way to monitor the status of your business unit’s applications as they progress to completion. For the data retrieved for each notification type, see the JSON schemas.

Notification type Description
application.accepted-priority-protected Application accepted and added to the daylist
application.accepted-priority-pending Application accepted and queuing for the daylist
application.validation-failed Application failed validation
application.error Application not added to the daylist due to a system error
application.correspondence-despatched A correspondence was raised on the application
application.attachment-success Document successfully attached to application
application.attachment-failed Document failed to attach to application
application.message-success Message successfully attached to application
application.message-failed Message failed to attach to application
application.cancelled Application cancelled
application.completed Application completed

Only certain notification types should prompt you to use the Application information API. For example, after retrieving a application.validation-failed notification for an application, use the Application information API to get a list of the validation errors.

Note:

The Application information API does not currently return the following information:

  • the status of attachments (application.attachment-success and application.attachment-failed)
  • the status of messages (application.message-success and application.message-failed)
  • the boolean field (was_subject_to_early_completion), which indicates that an application has been subject to early completion

Supported correspondence documents

Notifications currently support the following types of correspondence document.

Document code Name
ATP ATTACHED PLAN
CAN CANCELLATION LETTER
CMT COMPLETION OF TRANSACTION NOTIFICATION
DSR DATA SYNCHRONISATION ENQUIRIES RESULT
ECM EARLY COMPLETION LETTER
ECR EARLY COMPLETION OFFICIAL COPY OF THE REGISTER
EC6 EARLY COMPLETION 6 MONTH REMINDER
LRP LAND REGISTRY NOTICE PLAN/ILLUSTRATIVE PLAN
LTR LETTER
OCD OFFICIAL COPY OF A DOCUMENT
OCP OFFICIAL COPY OF THE TITLE PLAN
OCR OFFICIAL COPY OF THE REGISTER
PCD POSTAL CANCELLATION DOCUMENT
RCS REGISTRATION COMPLETION SHEET
REG COPY OF UPDATED REGISTER
ROA RESULT OF APPLICATION
TID TITLE INFORMATION DOCUMENT

Schemas

JSON schemas for each notification type can be found below:

Validation rules

There are no validation rules for implementing this API.

Example requests and responses

Get notifications request

GET /v1/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 /v1/notifications/acknowledge http/1.1

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

Acknowledge notifications response

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

application.accepted-priority-protected notification

{
  "data": [
    {
      "notification_id": "7788bfb3-02f2-4c9b-be58-94e9df010ac8",
      "created_datetime": "2025-02-25T16:17:19.120585661Z",
      "payload_schema": "https://landregistry.github.io/bgtechdoc/schemas/v1/application/accepted-priority-protected.json",
      "notification_type": "application.accepted-priority-protected",
      "subject_type": "APPLICATION",
      "subject": "3d4b51cf-76ab-40ad-9b09-099323034adf",
      "event_datetime": "2025-02-20T09:06:29.120585661Z",
      "status": "NEW",
      "payload": {
        "data": {
          "status": "ACCEPTED_PRIORITY_PROTECTED",
          "priority": "2025-02-20T09:06:29.04",
          "hmlr_reference": "A123ABR"
        }
      }
    }
  ]
}

application.validation-failed notification

{
  "data": [
    {
      "notification_id": "7788bfb3-02f2-4c9b-be58-94e9df010ac8",
      "created_datetime": "2025-02-25T16:17:19.120585661Z",
      "payload_schema": "https://landregistry.github.io/bgtechdoc/schemas/v1/application/validation-failed.json",
      "notification_type": "application.validation-failed",
      "subject_type": "APPLICATION",
      "subject": "3d4b51cf-76ab-40ad-9b09-099323034adf",
      "event_datetime": "2025-02-20T09:06:29.120585661Z",
      "status": "NEW",
      "payload": {
        "data": {
          "status": "VALIDATION_FAILED"
        }
      }
    }
  ]
}

Attach a message success notification

{  
  "errors ": [  
    {  
  "data": [  
    {  
      "notification_id": "7788bfb3-02f2-4c9b-be58-94e9df010ac8",  
      "created_datetime": "2025-02-25T16:17:19.120585661Z",  
      "payload_schema": "https://landregistry.github.io/bgtechdoc/schemas/v1/application/message-success.json",  
      "notification_type": "application.message-success",  
      "subject_type": "APPLICATION",  
      "subject": "3d4b51cf-76ab-40ad-9b09-099323034adf",  
      "event_datetime": "2025-02-20T09:06:29.120585661Z",  
      "status": "NEW",  
      "payload": {  
        "data": {  
          "attachment_id": 123  
        }  
      }  
    }  
  ]  
}

Attach a message failed notification

{  
  "data": [  
    {  
      "notification_id": "7788bfb3-02f2-4c9b-be58-94e9df010ac8",  
      "created_datetime": "2025-02-25T16:17:19.120585661Z",  
      "payload_schema": " https://landregistry.github.io/bgtechdoc/schemas/v1/application/message-failed.json ",  
      "notification_type": " application.message-failed",  
      "subject_type": "APPLICATION",  
      "subject": "3d4b51cf-76ab-40ad-9b09-099323034adf",  
      "event_datetime": "2025-02-20T09:06:29.120585661Z",  
      "status": "NEW",  
      "payload": {  
        "data": {  
          "failure_reason": "An error occurred"  
        }  
      }  
    }  
  ]  
}

When an application is completed, but subject to early completion

{
  "data": [
    {
      "notification_id": "13fd86a1-ca5d-48c5-9a3a-201f98b80a70",
      "created_datetime": "2026-06-15T09:20:03.703Z",
      "event_datetime": "2026-06-15T09:20:02.132Z",
      "payload_schema": "https://landregistry.github.io/bgtechdoc/schemas/v1/application/completed.json",
      "notification_type": "application.completed",
      "subject_type": "APPLICATION",
      "subject": "2e640fca-7550-425c-8ad1-51ef87ac32b2",
      "additional_provider_filter": null,
      "status": "NEW",
      "payload": {
        "data": {
          "status": "COMPLETED",
          "documents": [
            {
              "type": {
                "code": "RCS",
                "name": "REGISTRATION COMPLETION SHEET"
              },
              "created_at": "2026-06-15T09:20:02.616Z",
              "download_id": "a19dac826ecf5c1ca604ceff33fc109832b8d5a7d269a987199f49261c62f958"
            },
            {
              "type": {
                "code": "REG",
                "name": "COPY OF UPDATED REGISTER"
              },
              "created_at": "2026-06-15T09:20:02.701Z",
              "download_id": "852518c2cc217638fc02629ffd417138187ebfc44ee6db7b59e21e5d25dface4"
            }
          ],
          "hmlr_reference": "F185HBX",
          "application_request_id": "2e640fca-7550-425c-8ad1-51ef87ac32b2",
          "was_subject_to_early_completion": true
        }
      }
    }
  ]
}

When an early completion application receives ECM and ECR

The ECM (Early completion letter) and ECR (Early completion official copy of the register) are provided when the next application gives evidence of discharge.

{
  "data": [
    {
      "notification_id": "d3ca1fdf-d4ee-4f63-bf6f-6be37de6e882",
      "created_datetime": "2026-06-15T09:30:03.953Z",
      "event_datetime": "2026-06-15T09:30:02.359Z",
      "payload_schema": "https://landregistry.github.io/bgtechdoc/schemas/v1/application/correspondence-despatched.json",
      "notification_type": "application.correspondence-despatched",
      "subject_type": "APPLICATION",
      "subject": "2e640fca-7550-425c-8ad1-51ef87ac32b2",
      "additional_provider_filter": null,
      "status": "NEW",
      "payload": {
        "data": {
          "documents": [
            {
              "type": {
                "code": "ECM",
                "name": "EARLY COMPLETION LETTER"
              },
              "created_at": "2026-06-15T09:30:02.494Z",
              "download_id": "39d2c53730b8f5d9d9c69c05d0429e3b0bb91c974db5092b78521febce86eb46"
            },
            {
              "type": {
                "code": "ECR",
                "name": "EARLY COMPLETION OFFICIAL COPY OF THE REGISTER"
              },
              "created_at": "2026-06-15T09:30:02.891Z",
              "download_id": "4e8dbeb03ac6aa3c418cd5ef1d10f392c4cbc27a533dd9834fc8568568d5e0fb"
            }
          ],
          "hmlr_reference": "F185HBX",
          "application_request_id": "2e640fca-7550-425c-8ad1-51ef87ac32b2"
        }
      }
    }
  ]
}

Related APIs