The Companies House API lets you retrieve information about limited companies (and other companies that fall within the Companies Act 2006). The data returned is live and real-time, and is simple to use and understand.
If you are already familiar with JSON RESTful APIs, then you can jump straight in with the quick start guide.
Otherwise, read on for a quick tour of the essentials.
- Set up a Companies House account.
- Read the Companies House API overview.
- Gain an understanding of REST web services.
- Learn about the JSON data format.
- Learn about authentication.
- Explore the Companies House API.
- Developer guidelines.
- Rate limiting.
- Enumerated types.
Set up a Companies House account
To be able to explore and perform tests with the Companies House API, you need to register a user account with Companies House.
The Companies House API overview describes the basic operation of the API.
REST web services
REST, or Representational State Transfer, is an architectural software style in which standard HTTP requests are used to provide a simple and consistent approach to requesting and modifying data.
In a RESTful style of API, data resources are allocated unique URLs and
manipulated through standard HTTP verbs such as
GET to request a resource,
POST to create a resource,
PUT to change a resource, and
DELETE to remove a resource.
Further details on how the Companies House REST API works can be found in the introduction page.
The JSON data format
Further information can be found at json.org.
Access to all API services requires authentication. The Authorisation page describes the authorisation mechanism used by the Companies House API, and how to register your application.
Explore the API
Each Companies House API reference page contains an embedded "explorer" that allows the reader to try out the service in-situ, without having to write any client code at all.
There are some simple developer guidelines you can follow to help you achieve success with the Companies House API.
API rate limits
The Companies House API is subject to rate limiting to protect the quality of service for all users.
A majority of the resources returned by the Companies House API contain members that reference enumuration types. This helps make the resources self-documenting, and allow clients to interpret the meaning of a resource member without needing to otherwise parse a text description. Enumeration types are frequently used to supplement or replace a text description, which allows clients to display their own version of a description, more fitting their use case, or provide descriptions in multiple languages.
The collection of enumuration types used by Companies House are available on GitHub. These files provide a mapping between enumuration type and text description, and are divided into sets or classes. Each API resource member will define which class of enumuration is being returned.
A planned enhancement to the enumuration scheme is the provision of API endpoints that will return the enumuration class catalogue. This avoids having enumurations hard-coded within a client, and by periodically checking for change through ETags, avoids clients having to download the full catalogue unnecessarily.