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.
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.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 openedcertificate_timestamp,priority_type,applicant- if there is an existing official search certificate pending on the titleregistered_proprietor_names- if the names of the registered proprietor(s) given in the application do not agree with those shown on the registercommonhold_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
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_REGISTERPENDING_SEARCHES_OF_PARTDEVELOPER_TITLEACTUAL_FEE_EXCEEDS_EXPECTED_FEE
Validation
Validation diagram details the validation that the request undergoes.
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
| 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.
| 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
Vendor testing
Documents the data required for testing the service.