Skip to main content

Official Search of Whole (with Priority) with Data


Overview

An Official Search of Whole (with Priority) with Data protects agreements between buyers, sellers and lenders. The Official Search of Whole (with Priority) with Data RESTful API expands on the existing Official Search of Whole (with Priority) SOAP API, see HMLR Developer Pack here for information on the existing service.

Each service can be used:

  • when your application relates to the whole of the registered title to protect transfers, leases and mortgages.
  • both services prevent any registrations of adverse interest for 30 business days.

Each service will also tell you about:

  • alterations made to the register since the search from date
  • applications against the title that have not yet been completed
  • existing official searches
  • outline applications that are not protected by official search

The following sections relate to the Official Search of Whole (with Priority) with Data RESTful API service.

If You’re a Software Developer

Use this document to integrate data into your system.

Initially we expect users of the new RESTful version to have already integrated with the existing SOAP (v2.1) service.

Where an Official Search of Whole can’t be returned immediately (either lodged out of service hours or because it requires manual processing), then the RESTful service will confirm successful receipt, but the result will be available from the existing SOAP poll endpoint (https://businessgateway.landregistry.gov.uk/b2b/BGSoapEngine/OfficialSearchV2_1PollRequestWebService?wsdl). By far the majority of Official Searches of Whole are returned immediately and for those, the RESTful service will return the Official Search result certificate and additional JSON data elements detailing information contained within the result certificate PDF.

How the RESTful API Service Differs from the SOAP API Service

This service is an enhanced RESTful version of the original Official Search of Whole (with Priority) SOAP service. Within the service parameters, in the majority of cases, the Official Search certificate will be supplemented with data items in a JSON response relating to the result as follows:

Flags

Within the JSON response there are two flags, each providing a Boolean true/false response. These flags indicate the content revealed within the Official Search certificate.

  1. register_has_changed_since_search_from_date
    True - if the register has changed since the search from date, a value of true will be returned.
    False - if the register has not changed since the search from date, a value of false will be returned.

  2. result_contains_advisory_entries
    True - if the Official Search certificate (PDF) does contains further advisory entries in addition to whether the register has changed, a value of true will be returned.
    False - if the Official Search certificate (PDF) does not contain any further advisory entries in addition to whether the register has changed, a value of false will be returned.

Advisory Entries

When further advisory entries are contained in the certificate result, further detail is supplied for the following advisory entries:

  • there is an existing official search pending on the title
  • the names of the registered proprietor(s) provided do not agree with those shown on the register
  • the title number comprises a commonhold unit within a commonhold development

The complete text of each result entry present on the search certificate will be returned in the JSON response.

These advisory entries represent the most common entries but the Official Search certificate (PDF) may contain additional advisory entries.

Data Items Extracted from the Official Search Certificate

Additional data items relating to the official search result will also be returned within the JSON API response as follows:

  • official_copy_timestamp - if a new edition of the register has been opened
  • certificate_timestamp, priority_type, applicant - if there is an existing official search certificate pending on the title
  • registered_proprietor_names - if the names of the registered proprietor(s) given in the application do not agree with those shown on the register
  • commonhold_title_number - if the title number comprises a commonhold unit

This service is limited to immediate search results. When a result cannot be returned immediately, the official search certificate will become available via the existing Official Search of Whole (with Priority) SOAP API poll endpoint (https://businessgateway.landregistry.gov.uk/b2b/BGSoapEngine/Offi cialSearchV2_1PollRequestWebService?wsdl) and will not be supplemented with the JSON response data items. This will be the case when a search:

  • has been submitted outside of service working hours
  • requires manual processing

Process flow

Input

To request an official search, you will need to send:

  • login details
  • external reference number
  • title number
  • search start date
  • customer reference
  • registered proprietor or applicant for first registration
    • For one or more private individuals, enter the surname of one proprietor only
    • For companies, enter the full name including punctuation
    • Do not put a full stop at the end of the name
  • applicant name
  • priority type
  • contact details
  • property description
  • alternative despatch details

The following parameters will also be necessary if there are any complications, and may be supplied to keep transaction calls and processing times to a minimum.

  • NAME_MISMATCH_ON_REGISTER
  • PENDING_SEARCHES_OF_PART
  • DEVELOPER_TITLE
  • ACTUAL_FEE_EXCEEDS_EXPECTED_FEE

Validation

Validation diagram details the validation that the request undergoes.

1. Search of whole with priority via BG (business gateway) flow chart
Validation diagram Business Rules
Business Rule Decision point BG Code Message ID Message text
Internal business rule Does <Title number> exist on LR systems? N bg.title.invalid MSG-BG-010 Title number is invalid
BRL-ISBG-004 Is the <Title number> a caution title? Y bg.title.caution MSG-BG-074 Official Search cannot be lodged against a Caution Title
BRL-ISBG-011 Is the <Title number> closed ? Y bg.title.closed MSG-BG-014 This title number is closed
BRL-ISBG-034 Is the search from date valid? N bg.date.missing MSG-BG-038 Search from date is invalid
BRL-ISBG-026 Do <Search Names> match proprietors names? N Did request specify <Continue if Name Mismatch? N bg.state.nonamematch MSG-BG-035 There is no name match for this title number
Internal business rule Is the < Title number> a pending a pending FR?Y Are there any pending searches of part against <Title Number>? Y bg.title.pendingsearchofpart MSG-BG-012 The title has applications of part pending against it. If you intend to take a registrable disposition of part you should apply for an official search of part.
Internal business rule Is the < Title number> a pending FR?Y Are there any pending searches of part against <Title Number>? N Is the <Title Number> a developer title? Y Did customer specify continue if developer title? N bg.title.developertitle MSG-BG-013 This is a developing title. If you intend to take a registrable disposition of part you should apply for an official search with priority of part.
BRL-FEE-011 Calculate <Actual Fee> bg.fee.feeMismatch MSG-BG-032 Fee Amount provided does not match with the fee calculated by Land Registry
Various internal business rules (see work flow) Determine if result can be delivered electronically
Internal decision point Prepare acknowledgement response bg.officialSearch.sucessMessage MSG-BG-087 We have accepted your application for an official search with priority. Priority begins now and expires on <date>

Output

HM Land Registry will confirm when they receive a request for documents.


Service Working Hours

The Business Gateway service is available between 6.30am and 11pm. The Official Search of Whole (with Priority) with Data service will not be available between 11pm and 6.30am the following morning. Requests submitted out of service hours will be accepted but processing will drop to the SOAP Official Search of Whole (with Priority) service and will not include the supplementary data items. These times are in relation to the current time zone in London.


Access Control

To use this service, we would expect you to be an existing Business Gateway user and have already integrated with the Official Search of Whole (with Priority) SOAP API service. If you have an active user account, you will be able to access the new service using your existing credentials.

If you are not an existing user and would like to sign up to our service, you can request access at Apply for HM Land Registry Business e-services


Status Codes

When developing against the table below, please use the status code.

Success Codes

Success Codes
Status Title Type
201 Successful Request
202 Manual Processing Required BG20001
202 Submission Out of Hours BG20002

Error Codes

Error codes are currently in place but are subject to change or may disappear in the future.

A trace_id value uniquely identifies the request resulting in an error.

Error Codes
Status Title Type Detail
400 Invalid request body OS1API002 {field} is invalid
401 Invalid credentials or account is not active BG40004 Unauthorized
403 Incorrect user role or organisation is not permitted BG40005 Forbidden
409 Existing message id BG40011 Message ID has already been submitted
422 Invalid title bg.title.invalid Title Number is invalid
422 Name mismatch and not continue bg.state.nonamematch There is no name match for this title
422 Closed title bg.title.closed Title number is closed
422 Fee mismatch bg.fee.feeMismatch Fee amount provided does not match with the fee calculated by Land Registry
422 Search from date is in the future bg.date.futuredate Search from date is invalid
422 Developer title and not continue bg.title.developertitle This is a developing title. If you intend to take a registrable disposition of part you should apply for an official search with priority of part
422 Pending search and not continue bg.title.pendingsearchofpart The title has applications of part pending against it. If you intend to take a registrable disposition of part you should apply for an official search of part
422 Caution title bg.title.caution Official Search cannot be lodged against a Caution Title
429 Request limit exceeded BG40006 Too many requests, please wait and try again
500 No specific exception BG50001 Internal server error
503 Service is down for a non-specific reason BG50002 Service unavailable
504 Internal service timeout BG50004 Gateway timeout

Customer Test Stubs

Endpoint URL

The test environment can be accessed at https://bgtest.landregistry.gov.uk/bg2test/api

This requires a customer test certificate (this is different to the production client certificates).


Schemas

A Generic document thumbnail image

OpenAPI Schema

YAML
This file may not be suitable for users of assistive technology.

Download


Vendor testing

Documents the data required for testing the service.

A Generic document thumbnail image

Vendor Test data (request official search of whole)

PDF, 587KB, 34 pages
This file may not be suitable for users of assistive technology.

Download