Skip to main content
Back to Overview Back to Home

Application Information API

The Application information API also includes information about an application, including:

  • the current state of the application
  • the application_request_id used in the request
  • an ID for the accepted application, hmlr_reference, once accepted (previously known as ABR)
  • the priority of the application, priority_timestamp, once accepted
  • any errors that prevented application submission
  • any warnings that did not prevent submission, but need to be addressed before a caseworker can process the application, otherwise a requisition may occur

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, see the Submit an application notifications section.

View the API Specification

See the API Specification here

How the service API works

Interaction diagram

State diagram

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 Application information service API

The Application information API is used to get detailed information about a specific application, using the application_request_id returned by the Submit an application API request.

The status of an application can currently be one of the following:

  • VALIDATING - HM Land Registry are still processing the application, and it has not yet been added to the day list
  • VALIDATION_FAILED - The application has not been added to the day list due to errors during validation. The errors found are included in the errors section of the response
  • ACCEPTED_AWAITING_PRIORITY - The application has passed validation but has not yet been added to the day list as it is currently closed. The application will be added to the day list and moved to an ACCEPTED_PRIORITY_PROTECTED state when the day list reopens
  • ACCEPTED_PRIORITY_PROTECTED - The application has been accepted onto the day list, and has priority
  • SYSTEM_ERROR - The application has not been added to the day list due to an HM Land Registry system error. The request should be retried, or the support team contacted

This API will always return a HTTP 200 response for a valid request, regardless of the status of the application.

Other information other than status and application_request_id may not be included in a response if that data is not available. For example, the hmlr_reference will not be returned if the application is in a VALIDATION_FAILED state.

Validation rules

There are no validation rules for implementing this service API.

Example requests and responses

GET /v0/applications/{id}/status - VALIDATING status

{
  "data": {
    "status": "VALIDATING", 
    "application_request_id": "3e4f6da2-ada7-4081-957c-b23542466715" 
  }
}

GET /v0/applications/{id}/status - ACCEPTED_PRIORITY_PROTECTED status

{
  "data": {
    "status": "ACCEPTED_PRIORITY_PROTECTED", 
    "application_request_id": "3e4f6da2-ada7-4081-957c-b23542466715", 
    "hmlr_reference": "AB1234", 
    "priority_timestamp": "2024-09-25T18:18:49Z",
    "warnings": [
      "You must upload document X"
    ]
  }
}

GET /v0/applications/{id}/status - VALIDATION_FAILED status

{ 
  "data": {
    "status": "VALIDATION_FAILED", 
    "application_request_id": "3e4f6da2-ada7-4081-957c-b23542466715", 
    "errors": [
      {
        "type": "OC018",
        "detail": "Failed to get document '00001'.",
        "pointer": null
      }
    ]
  }
}

GET /v0/applications/{id}/status - ACCEPTED_AWAITING_PRIORITY status

{ 
  "data": {
    "status": "ACCEPTED_AWAITING_PRIORITY", 
    "application_request_id": "3e4f6da2-ada7-4081-957c-b23542466715" 
  }
}

Test Stubs

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

1. Information of Application with Single Charge

Request

Method: GET

Endpoint: /v0/applications/b3ac19be-2b6d-4b8a-971c-e758b0e8e790/information

Headers:

  • Authorization: <any-value>

Response

Status: 200

Body:

{
  "data": {
    "application_request_id": "b3ac19be-2b6d-4b8a-971c-e758b0e8e790",
    "status": "ACCEPTED_PRIORITY_PROTECTED",
    "priority_timestamp": "2024-09-25T18:18:49Z",
    "hmlr_reference": "A123AAA",
    "errors": []
  }
}

2. Information of Application with Single Transfer

Request

Method: GET

Endpoint: /v0/applications/2563940e-ae95-4e7e-9b33-49a6571abdf6/information

Headers:

  • Authorization: <any-value>

Response

Status: 200

Body:

{
  "data": {
    "application_request_id": "2563940e-ae95-4e7e-9b33-49a6571abdf6",
    "status": "ACCEPTED_PRIORITY_PROTECTED",
    "priority_timestamp": "2024-09-25T18:18:49Z",
    "hmlr_reference": "B123BBB",
    "errors": []
  }
}

3. Information of Application with Level 2 Validation Errors

Request

Method: GET

Endpoint: /v0/applications/3be62ad3-c542-452d-975e-6cd18d77196f/information

Headers:

  • Authorization: <any-value>

Response

Status: 200

Body:

{
  "data": {
    "status": "VALIDATION_FAILED",
    "hmlr_reference": null,
    "priority_timestamp": null,
    "errors": [{
      "type": "mdref-on-record",
      "detail": "MD Ref MD007A does not exist on record",
      "pointer": null
    }, {
      "type": "lender-name-matches-records",
      "detail": "MD Ref MD007A not found on record",
      "pointer": null
    }, {
      "type": "all-mandatory-documents-provided",
      "detail": "Mandatory documents missing for transactions of type [T]",
      "pointer": null
    }, {
      "type": "transferee-has-representation-type",
      "detail": "Transferee Transferee must have a representation type",
      "pointer": null
    }],
    "warnings": [],
    "application_request_id": "3be62ad3-c542-452d-975e-6cd18d77196f"
  }
}

See more