Notifications API test stubs
Version and Status
HMLR does not currently provide a test environment for integrators using our Business Gateway APIs. Instead, we’ve provided example code for different scenarios to demonstrate what you should expect to see when developing your own services.
Base URL: https://bgtest.landregistry.gov.uk/bg2test/api
Scenario 1: Get all notifications
Request
Method: GET
Endpoint: /v1/notifications
Headers: Authorization: <any-value>
Response
Status: 200
{
"data": [
{
"notification_id": "{{ID}}",
"created_datetime": "2024-01-01T12:00:00.000Z",
"event_datetime": "2024-01-01T12:00:00.000Z",
"payload_schema": "https://landregistry.github.io/bgtechdoc/schemas/v1/application/accepted-priority-protected.json",
"notification_type": "application.accepted-priority-protected",
"subject_type": "APPLICATION",
"subject": "b3ac19be-2b6d-4b8a-971c-e758b0e8e790",
"additional_provider_filter": "subUnit1",
"status": "ACKNOWLEDGED",
"payload": {
"data": {
"hmlr_reference": "ABC456A",
"status": "ACCEPTED_PRIORITY_PROTECTED",
"priority": "2024-09-20T09:56:46.123123Z"
}
}
},
{
"notification_id": "{{ID}}",
"created_datetime": "2024-01-01T12:00:00.000Z",
"event_datetime": "2024-01-01T12:00:00.000Z",
"payload_schema": "https://landregistry.github.io/bgtechdoc/schemas/v1/application/accepted-priority-protected.json",
"notification_type": "application.accepted-priority-protected",
"subject_type": "APPLICATION",
"subject": "2563940e-ae95-4e7e-9b33-49a6571abdf6",
"additional_provider_filter": "subUnit1",
"status": "NEW",
"payload": {
"data": {
"hmlr_reference": "ABC456B",
"status": "ACCEPTED_PRIORITY_PROTECTED",
"priority": "2024-09-20T09:56:46.123123Z"
}
}
},
{
"notification_id": "{{ID}}",
"created_datetime": "2024-01-01T12:00:00.000Z",
"event_datetime": "2024-01-01T12:00:00.000Z",
"payload_schema": "https://landregistry.github.io/bgtechdoc/schemas/v1/application/validation-failed.json",
"notification_type": "application.validation-failed",
"subject_type": "APPLICATION",
"subject": "3be62ad3-c542-452d-975e-6cd18d77196f",
"additional_provider_filter": "subUnit1",
"status": "NEW",
"payload": {
"data": {
"status": "VALIDATION_FAILED"
}
}
}
]
}
Scenario 2: Get all new notifications
Request
Method: GET
Endpoint: /v1/notifications?status=NEW
Headers: Authorization: <any-value>
Response
Status: 200
{
"data": [
{
"notification_id": "{{ID}}",
"created_datetime": "2024-01-01T12:00:00.000Z",
"event_datetime": "2024-01-01T12:00:00.000Z",
"payload_schema": "https://landregistry.github.io/bgtechdoc/schemas/v1/application/accepted-priority-protected.json",
"notification_type": "application.accepted-priority-protected",
"subject_type": "APPLICATION",
"subject": "2563940e-ae95-4e7e-9b33-49a6571abdf6",
"additional_provider_filter": "subUnit1",
"status": "NEW",
"payload": {
"data": {
"hmlr_reference": "ABC456B",
"status": "ACCEPTED_PRIORITY_PROTECTED",
"priority": "2024-09-20T09:56:46.123123Z"
}
}
},
{
"notification_id": "{{ID}}",
"created_datetime": "2024-01-01T12:00:00.000Z",
"event_datetime": "2024-01-01T12:00:00.000Z",
"payload_schema": "https://landregistry.github.io/bgtechdoc/schemas/v1/application/validation-failed.json",
"notification_type": "application.validation-failed",
"subject_type": "APPLICATION",
"subject": "3be62ad3-c542-452d-975e-6cd18d77196f",
"additional_provider_filter": "subUnit1",
"status": "NEW",
"payload": {
"data": {
"status": "VALIDATION_FAILED"
}
}
}
]
}
Scenario 3: Get all acknowledged notifications
Request
Method: GET
Endpoint: /v1/notifications?status=ACKNOWLEDGED
Headers: Authorization: <any-value>
Response
Status: 200
{
"data": [
{
"notification_id": "{{ID}}",
"created_datetime": "2024-01-01T12:00:00.000Z",
"event_datetime": "2024-01-01T12:00:00.000Z",
"payload_schema": "https://landregistry.github.io/bgtechdoc/schemas/v1/application/accepted-priority-protected.json",
"notification_type": "application.accepted-priority-protected",
"subject_type": "APPLICATION",
"subject": "b3ac19be-2b6d-4b8a-971c-e758b0e8e790",
"additional_provider_filter": "subUnit1",
"status": "ACKNOWLEDGED",
"payload": {
"data": {
"hmlr_reference": "ABC456A",
"status": "ACCEPTED_PRIORITY_PROTECTED",
"priority": "2024-09-20T09:56:46.123123Z"
}
}
}
]
}
Scenario 4: Get all with invalid date filter
Request
Method: GET
Endpoint: /v1/notifications?created_after=2020-01-01T00:00:00&created_before=2015-01-01T00:00:00
Headers: Authorization: <any-value>
Response
Status: 400
{
"type": "https://problems-registry.smartbear.com/bad-request/",
"title": "Bad Request",
"status": 400,
"detail": "created_after parameter cannot be after created_before parameter",
"instance": "/v1/notifications",
"code": "400-01"
}
Scenario 5: Acknowledge notifications
Request
Method: POST
Endpoint: /v1/notifications/acknowledge
Headers: Authorization: <any-value>
{
"data": [
"b3ac19be-2b6d-4b8a-971c-e758b0e8e790",
"87654321-2b6d-4b8a-971c-e758b0e8e790",
"12345678-2b6d-4b8a-971c-e758b0e8e790"
]
}
Response
Status: 200
{
"data": {
"acknowledged": [
"b3ac19be-2b6d-4b8a-971c-e758b0e8e790"
],
"not_found": [
"87654321-2b6d-4b8a-971c-e758b0e8e790",
"12345678-2b6d-4b8a-971c-e758b0e8e790"
]
}
}
Scenario 6: Application queued notification
Request
Method: GET
Endpoint: /v1/notifications?notification_type=application.accepted-priority-pending
Headers: Authorization: <any-value>
Response
Status: 200
{
"data": [{
"notification_id": "{{ID}}",
"created_datetime": "2024-01-01T12:00:00.000Z",
"event_datetime": "2024-01-01T12:00:00.000Z",
"payload_schema": "https://landregistry.github.io/bgtechdoc/schemas/v1/application/accepted-priority-pending.json",
"notification_type": "application.accepted-priority-pending",
"subject_type": "APPLICATION",
"subject": "45454545-2b6d-4b8a-971c-e758b0e8e790",
"additional_provider_filter": "subUnit1",
"status": "NEW",
"payload": {
"data": {
"status": "ACCEPTED_AWAITING_PRIORITY"
}
}
}]
}
Scenario 7: Application error notification
Request
Method: GET
Endpoint: /v1/notifications?notification_type=application.error
Headers: Authorization: <any-value>
Response
Status: 200
{
"data": [{
"notification_id": "{{ID}}",
"created_datetime": "2024-01-01T12:00:00.000Z",
"event_datetime": "2024-01-01T12:00:00.000Z",
"payload_schema": "https://landregistry.github.io/bgtechdoc/schemas/v1/application/error.json",
"notification_type": "application.error",
"subject_type": "APPLICATION",
"subject": "45454545-2b6d-4b8a-971c-e758b0e8e790",
"additional_provider_filter": "subUnit1",
"status": "NEW",
"payload": {
"data": {
"status": "SYSTEM_ERROR"
}
}
}]
}
Scenario 8: Application cancelled notification
Request
Method: GET
Endpoint: /v1/notifications?subject=<uuid ending with 'can'>
Headers: Authorization: <any-value>
Response
Status: 200
{
"data": [
{
"notification_id": "50cda861-ba0b-41dc-af9a-4748335d51ad",
"created_datetime": "2025-09-05T08:13:38.076Z",
"event_datetime": "2025-09-05T08:13:38.052Z",
"payload_schema": "https://landregistry.github.io/bgtechdoc/schemas/v1/application/accepted-priority-protected.json",
"notification_type": "application.accepted-priority-protected",
"subject_type": "APPLICATION",
"subject": "a97679c9-624f-4680-ae8b-15b7-r411can",
"additional_provider_filter": null,
"status": "NEW",
"payload": {
"data": {
"status": "ACCEPTED_PRIORITY_PROTECTED",
"priority": "2025-09-05T08:13:37.697377Z",
"hmlr_reference": "R411CAN"
}
}
},
{
"notification_id": "302ce5d2-cb99-4696-b661-767c76caa07c",
"created_datetime": "2025-09-05T08:20:04.695Z",
"event_datetime": "2025-09-05T08:20:03.776Z",
"payload_schema": "https://landregistry.github.io/bgtechdoc/schemas/v1/application/cancelled.json",
"notification_type": "application.cancelled",
"subject_type": "APPLICATION",
"subject": "a97679c9-624f-4680-ae8b-15b7-r411can",
"additional_provider_filter": null,
"status": "NEW",
"payload": {
"data": {
"status": "CANCELLED",
"documents": [
{
"type": {
"code": "CAN",
"name": "CANCELLATION LETTER"
},
"created_at": "2025-09-05T08:20:04.050Z",
"download_id": "can_62523897b09f9a3f380eefd878e7205aac78781cc68383ba79c3b7d42385"
}
],
"hmlr_reference": "R411CAN",
"application_request_id": "a97679c9-624f-4680-ae8b-15b7-r411can"
}
}
}
]
}
Scenario 9: Application completed notification
Request
Method: GET
Endpoint: /v1/notifications?subject=<uuid ending with 'cmp'>
Headers: Authorization: <any-value>
Response
Status: 200
{
"data": [
{
"notification_id": "5e6f6865-270f-43da-87b6-4af759f3c2aa",
"created_datetime": "2025-09-05T08:07:56.346Z",
"event_datetime": "2025-09-05T08:07:56.320Z",
"payload_schema": "https://landregistry.github.io/bgtechdoc/schemas/v1/application/accepted-priority-protected.json",
"notification_type": "application.accepted-priority-protected",
"subject_type": "APPLICATION",
"subject": "28a01655-544a-48c5-9e40-4ac2-p311cmp",
"additional_provider_filter": null,
"status": "NEW",
"payload": {
"data": {
"status": "ACCEPTED_PRIORITY_PROTECTED",
"priority": "2025-09-05T08:07:55.975284Z",
"hmlr_reference": "P311CMP"
}
}
},
{
"notification_id": "ac603b14-7c62-431a-99e6-66aca3cdb717",
"created_datetime": "2025-09-05T08:15:02.333Z",
"event_datetime": "2025-09-05T08:15:00.712Z",
"payload_schema": "https://landregistry.github.io/bgtechdoc/schemas/v1/application/completed.json",
"notification_type": "application.completed",
"subject_type": "APPLICATION",
"subject": "28a01655-544a-48c5-9e40-4ac2-p311cmp",
"additional_provider_filter": null,
"status": "NEW",
"payload": {
"data": {
"status": "COMPLETED",
"documents": [
{
"type": {
"code": "LTR",
"name": "LETTER"
},
"created_at": "2025-09-05T08:15:01.281Z",
"download_id": "ltr_6a1756a68fbe29c58fe75e9c7a261dd416692f8a0d916ac63aead8111549"
},
{
"type": {
"code": "RCS",
"name": "REGISTRATION COMPLETION SHEET"
},
"created_at": "2025-09-05T08:15:01.319Z",
"download_id": "rcs_4efc428e900f2d1501c156e9ec664f2a740749b6689afe61b6bf95440a31a"
},
{
"type": {
"code": "REG",
"name": "COPY OF UPDATED REGISTER"
},
"created_at": "2025-09-05T08:15:01.343Z",
"download_id": "reg_7ea12372179f1ae9d80fefec38cb7ff6b42672c49a0c292827434c848038"
}
],
"hmlr_reference": "P311CMP",
"application_request_id": "28a01655-544a-48c5-9e40-4ac2-p311cmp",
"was_subject_to_early_completion": false
}
}
}
]
}
Scenario 10: Application requisitioned notification
Request
Method: GET
Endpoint: /v1/notifications?subject=<uuid ending with 'app'>
Headers: Authorization: <any-value>
Response
{
"notification_id": "{{ID}}",
"created_datetime": "2024-01-01T12:00:00.000Z",
"event_datetime": "2024-01-01T12:00:00.000Z",
"payload_schema": "https://landregistry.github.io/bgtechdoc/schemas/v1/application/correspondence-despatched.json",
"notification_type": "application.correspondence-despatched",
"subject_type": "APPLICATION",
"subject": "28a01655-544a-48c5-9e40-4ac2-p311app",
"additional_provider_filter": null,
"status": "NEW",
"payload": {
"data": {
"documents": [
{
"type": {
"code": "LTR",
"name": "LETTER"
},
"created_at": "2025-09-05T08:15:01.281Z",
"download_id": "ltr_6a1756a68fbe29c58fe75e9c7a261dd416692f8a0d916ac63aead8111549"
}
],
"hmlr_reference": "P311APP",
"application_request_id": "28a01655-544a-48c5-9e40-4ac2-p311app"
}
}
}