Companies House REST API

The Companies House API is a REST API that provides a simple, consistent approach to requesting and modifying data. REST stands for Representational State Transfer which is an architectural software style in which standard HTTP request methods are used to retrieve and modify representations of data. This is identical to the process of retrieving a web page or submitting a web form.

Previous versions of the Companies House API implemented an XML-RPC style of interface. Data was retrieved or submitted by POSTing XML documents to the service. Each version defined the method to be called and the data to be processed.

The difference between both API approaches is explained below.

Representational State Transfer (REST) web services

In a RESTful style of API, data resources are allocated unique URLs and manipulated through standard HTTP verbs such as:

1. GET to request a resource
2. POST to create a resource
3. PUT to change a resource
4. DELETE to remove a resource

In contrast to the above XML-RPC examples, the same RESTful API request for a customer record would be:

GET https://api.example.domain/customer/12345 HTTP/1.1

The resource request is made using the GET method with no request body.

In a RESTful API, a resource is modified by POSTing a revised resource representation, in this case JSON, to the same resource URL:

POST https://api.example.domain/customer/12345 HTTP/1.1

Content-Type: text/json

{
    "CustomerName": "Joe Bloggs",
    "Address"      : "",
    "etc"           : "etc"
}

Similarly, a resource may be deleted by sending a DELETE request to the resource URL:

DELETE https://api.example.domain/customer/12345 HTTP/1.1

REST uses the existing features of the HTTP protocol and does not permit the designer to define application specific operations. Also, because each resource has a globally unique URI and is able to make use of the GET method for resource requests, these APIs benefit from existing network components such as caches, proxies and intelligent routing.

The JSON data format

JSON, or JavaScript Object Notation, is an open, standard format for storing and exchanging data. It is easier to use than XML and more compact. It can be used as a data format by any programming language, which makes it ideal for HTTP-based API services.

API specifications

The API specifications list in the Developer's API suite documents all of the available Companies House public API operations, from reading public company data to submitting a data change for a specific company.

API specifications for all Companies House public API operations are documented using OpenAPI specifications.