Skip to main content
Get started

Terms of use

The terms of use policies explain what users can expect when creating and operating software services that use Business Gateway APIs.

Versioning policy

This versioning policy outlines Business Gateway’s process for making changes to its APIs.

HMLR reserves the right to introduce:

  • up to 4 major versions of any API per year
  • unlimited minor changes to existing APIs

Making these changes will mean continuing to provide a faster and more responsive service but we understand they may also disrupt the work of our customers. As a result, we’ll be clear about the changes we’re making, and when, so you can understand the risks and benefits to your own systems and ways of working.

Release versioning

We follow the Semantic Versioning 2.0.0 system (opens in new tab).

Minor version releases

Any minor changes to existing API versions will be backwards compatible and will not require any immediate changes by our customers. The OpenAPI specification shows the full version number MAJOR.MINOR.PATCH, and regular release notes are published to notify you of changes.

Major version releases

When we release a major version of an API, the version numbers of all affected endpoint URLs are incremented to denote a breaking change, using the format vX. For example, the POST /v1/applications endpoint would be updated to POST /v2/applications.

To avoid unnecessary updates, groups of APIs are versioned independently. For example, for the Submit an application to the Land Registry APIs, version 2 of the Submit an application API (POST /v2/applications) is compatible with version 1 of the Download a document API (GET /v1/documents/{document_id}) unless stated otherwise.

After a major version of an API is released, we’ll allow six months between the deprecation and decommissioning of old versions.

How we’ll support you to make changes

Where possible, we’ll provide you with access to our sandbox test environment to run new versions of APIs before they go live, or to test stubs. We’ll also provide API schema documentation in the form of OpenAPI specifications, and release notes. This should help you to understand how any changes might impact your systems. We may also provide other resources, including:

  • diagrams and visuals
  • best practice examples

When to expect changes

We know that changes will impact our customers differently and have factored this into how we communicate with you. We’ll be clear about deadlines for integrating new versions of services and provide advanced notice when services will be deprecated and decommissioned.

Below you’ll find a step-by-step guide to help you understand how and when we’ll implement changes:

  1. Step1 Announcement of a new service or version

    1. The first step will be to inform you of a new service or version. This will allow you to plan before the API specification is released. Further information about timelines will also be sent ahead of the release date.

  2. Step 2 API specification is released

    1. The API specification for the new service or version will be released before we expect you to start building to it.

  3. Step 3 Service or version is made available in sandbox test environment

    1. Where possible, we’ll provide you with access to our sandbox to run new versions of APIs before they go live. In some cases, the sandbox and live versions will be released at the same time.

  4. Step 4 Service or version is live

    1. At this stage, you’ll have access to use the service or version in your own live environment. While in this live state, we'll continue to provide maintenance updates to the service.

  5. Step 5 Service or version is deprecated

    1. In cases where a service is deprecated, you’ll still be able to use it, but it will no longer receive maintenance updates. We’ll aim to provide you with six months' notice to migrate to a new version after announcing the deprecation of a service or old version.

  6. Step 6 Service or version is decommissioned

    1. After the deprecation period, the old service or version will be removed and become unavailable.

For any questions about our versioning policy, please contact the integration support team.

System security

All users of the network are responsible for maintaining up-to-date system patches, security updates, anti-virus software and other countermeasures to protect their systems.

Any software that could interact with HM Land Registry systems should be thoroughly tested and you must have your own testing procedures and policies in place and apply them rigorously.

Some free/beta programs can contain bugs or viruses, which could pose a threat to HM Land Registry systems. Applications and operating system software should only be implemented in operational systems after extensive and successful testing.

Testing should be done in a secure environment with non-sensitive data. Access to system files and program source code should be controlled.

We sometimes use technical terms to describe the work we do at HMLR. For a list of commonly used terms and their definitions, visit our glossary.