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 - only retrieve notifications with the specific subject. The only subject currently available is application. More subjects will be available as the API is developed further.
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 endpoint 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

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

These notifications will contain the following information:

application.accepted-priority-protected, application.accepted-priority-pending and application.error will contain the updated application status only
application.accepted-priority-protected will contain updated application status, the priority of the application and the HMLR reference for the accepted application
application.correspondence-despatched, application.cancelled and application.completed will contain a list of correspondence documents that can be downloaded using the download a document API.

To get more detailed information about an application that caused the notification, you can usually use the application information API. For example, after receiving an application.validation-failed notification, use the Application information API to get a list of the validation errors. However, the application information API does not currently return information related to attachments, messages or early completion.

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"
        }
      }
    }
  ]
}