Documentation
/api/findcompanies
This API endpoint returns a list of companies that match the provided criteria.
Request
https://convert-ixbrl.co.uk/api/findcompanies?apiversion=1&[Add atleast one parameter here]
Rate limit
This endpoint is rate limited to 1 request per 2 seconds while the service is in early preview with requests exceeding this limit served with HTTP 429 code
Authentication
This endpoint requires the authentication header to be supplied. See the authentication section.
Request Parameters
Name Type Optional Description
apiVersion
 string No API Version, currently on "1"
searchTerm
 string Yes Full or partial company name
minNetAssetsLiabilities
 float Yes Minimum net assets or liabilities figure for the last available financial year , for example 500000
maxNetAssetsLiabilities
 float Yes Maximum net assets or liabilities figure for the last available financial year, for example 60000000
minTurnover
 float Yes Minimum turnover figure for the last available financial year,, for example 500000
maxTurnover
 float Yes Maximum turnover figure for the last available financial year, for example 60000000
location
 string Yes Full or partial postcode, city or town of the registered address
industries
 array Yes An array of string values containing one or more SIC codes, for example ["01110","01120"]. A complete list of SIC codes can be found on the Companies House website
incorporationDateFrom
 string Yes Incorporation From Date to only include companies created on or after the specified date. The date needs to be in "dd/MM/yyyy" format, for example August 1, 2020 should be sent across as "01/08/2020"
incorporationDateTo
 string Yes Incorporation To Date to only include companies created before or on the specified date. The date needs to be in "dd/MM/yyyy" format, for example August 12, 2020 should be sent across as "12/08/2020"
HTTP Response codes
Status Code Description
200 Successful requests with results
204 Successful requests with no results
400 Validation errors
401 Authorisation error for when the secret key header is missing or is invalid
429 Request throttled for exceeding rate limits

Response JSON Sample

This preview version will return up to 1000 results per search

{
    "status": "Ok",
    "totalResults": 1000,
    "pageNumber":0,
    "pageSize": 50,
    "result": [
          {
            "companyNumber": "1234567",
            "title": "A company limited",
            "companyIncorporated": "19/01/2018",
            "companyRegisteredAddress": "20-22 WENLOCK ROAD,LONDON,N1 7GU",
            "companyStatus": "Active",
            "netAssetsLiabilities": 63529000,
            "turnover": 1000000,
            "resultNumber": 100,   
          },
          {
            "companyNumber": "2345678",
            "title": "B company holdings",
            "companyIncorporated": "15/03/2017",
            "companyRegisteredAddress": "10-12 KING STREET,LONDON,N1 9NG",
            "companyStatus": "Active",
            "netAssetsLiabilities": 45200000,
            "turnover": 750000,
            "resultNumber": 101    
          },
          {
            "companyNumber": "3456789",
            "title": "C company services",
            "companyIncorporated": "22/08/2019",
            "companyRegisteredAddress": "30-32 QUEEN ROAD,LONDON,N1 8QE",
            "companyStatus": "Active",
            "netAssetsLiabilities": 32000000,
            "turnover": 500000
            "resultNumber": 102
          }
    ]
}

Response Properties

Name Type Nullable Description
status
 string no Contains
Ok
if the request was successful,
Error
if there was an error.
result[]
 array yes Contains the list of companies matching the search criteria provided, including the available financial figures for each company
Fields shown below are part of each item of result[] array
companyNumber
 string no Contains the Companies House registration number for the company
title
 string no Name of the company
companyIncorporated
 string no Date of incorporation in "dd/MM/yyyy" format
companyRegisteredAddress
 string no Registered address of the company
companyStatus
 string no Registration status of the company. The list of available statuses can be seen on this Companies House Github project
netAssetsLiabilities
 float yes Latest Net Assets/ Liabilities figure , when available
turnOver
 float yes Latest Turnover figure, when available
resultNumber
 integer no Search results position for this company