Companies House API v1.0
The Companies House API is a free REST based service offered by the UK government to provide information relating to companies and officers including:
- Company search and company profile data
- Company officers, officer appointments and disqualifications
- Company filing history
- Company insolvency and charges information
- Persons and entities with significant control
Note: The Companies House API was still in Beta at the time of implementation.
Please include this in your consideration when using the service and if any unexpected errors arise please report
these to The Avoka Exchange Team.
This first implementation utilises only a subset of the available services to support simple company searches based
on Company Name or Company Number. To request inclusion of other services please send
your request to The Avoka Exchange Team with a description of the use cases
you are targeting.
The Maestro Library included in this package contains a auto-suggest style Company Quick Search field that performs lookups on company name and/or company number as you type and presents matching options in a list that drops down under the search field. Users can then select the correct record from the list.
Licensing
The Companies House API is provided by the UK Government as a free service. Clients must register an account and apply for an API key before using the service.
The service applies a request rate limit of 600 requests within a five minute period (2 per second), but you are able to request a higher rate limit if required. See Rate Limiting.
Compatibility
This package has the following compatibility requirements:
| Module | Compatibility | Notes |
|---|---|---|
| Transact Manager | 5.0 or above | |
| Transact Maestro | 5.0.14 or above |
Installation Instructions
To install this package please walk through the following proceedure:
- Unzip the package to a directory on your computer
- Import each zip archive found in the services folder to Transact Manager under the Services >> All Services menu item.
- Review the Help Doc tab for each of the imported services and make any required adjustments to service parameters.
- Review the Service Connection requirements under the same Help Doc tab for each of the imported services and make any required configurations to the Service Connection. Service Connections can be configured in Transact Manager under the Services >> Service Connections menu item.
- Import each archive found in the libraries folder to Maestro. Importing these into the Organisation level libraries folder is recommended as this will make the components available to all projects, however they can be imported at the Project level if required.
Usage Instructions
In Maestro, you can add the Company Quick Search field to your form by locating it in your palette and dragging it to the
desired location. To map the data from the user selected company into field in your form, open the DDS Configuration
section of the Properties tab and complete the First Response Field Map configuration.
Maestro Assets
Auto-suggest style lookup on UK companies based on full or partial company name or company number
Service Calls
Rule Templates
You may add your own logic to handle the following rule types triggered by this component:
- On Success : a script to run on success of the dynamic data call, the parameter info contains the response
- On List Item Select : a script to run on the click of a result
- On Extra Item Select : a script to run on the click of an extra item
Services
Service Connection
Compatibility
| Module | Compatibility |
|---|---|
| Manager | 5.0 |
Service Parameters
| Name | Description | Required | Default |
|---|---|---|---|
| maxResultSize | Default value for maximum number of matching search results returned from the search function (default 10). This value can be overridden as a request parameter if required. Must be between 1 and 20. | Yes |
10
|
Inputs
| Name | Description | Required |
|---|---|---|
| searchString | The company search string could include full or partial company name or company number | Yes |
| maxResultSize | Optionally specify a numeric maximum result list size to override the default: 10. Cannot be less than 1 or greater than 20. | No |
Outputs
| Name | Description |
|---|---|
| [] | The results are provided as a JSON array of objects with the following attributes: |
| [].label | The label to diaplay in search results lists such as auto-complete fields - this label includes company title and company number |
| [].title | The company title |
| [].description | The API provided description |
| [].companyNumber | The company number |
| [].status | The company registration status |
| [].dateOfCreation | The date the company was incorporated in the format yyyy-MM-dd |
| [].dateOfCessation | The date the company was disolved in the format yyy-MM-dd |
| [].fullAddress | The full company address |
Address Details:
|
The company address fields broken out |
| [].url | The url to the company record in the Company House API |
Service Connections
The following service connections are used by this package.
| Property Name | Description | Required |
|---|---|---|
| Type | HTTP Endpoint | Yes |
| Endpoint |
Must point to the Companies House base endpoint https://api.companieshouse.gov.uk
|
Yes |
| Auth Key | The API key issued to your organization by Companies House | Yes |