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 with requests exceeding this limit served with HTTP 429 code. Limit increase requests can be sent to support@convert-ixbrl.co.uk
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.0
maxNetAssetsLiabilities
 float Yes Maximum net assets or liabilities figure for the last available financial year, for example 60000000.0
minTotalAssetsLessCurrentLiabilities
 float Yes Minimum total assets less current liabilities figure for the last available financial year, for example 60000000.0
maxTotalAssetsLessCurrentLiabilities
 float Yes Maximum total assets less current liabilities figure for the last available financial year, for example 80000000.0
minTurnover
 float Yes Minimum turnover figure for the last available financial year, for example 500000.0
maxTurnover
 float Yes Maximum turnover figure for the last available financial year, for example 60000000.0
minCash
 float Yes Minimum cash at hand/at bank figure for the last available financial year, for example 500000.0
maxCash
 float Yes Maximum cash at hand/at bank figure for the last available financial year, for example 600000.0
minEmployees
 integer Yes Minimum average number of employees figure for the last available financial year, for example 10
maxEmployees
 integer Yes Minimum average number of employees figure for the last available financial year, for example 20
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 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 500 results per search

{
    "status": "Ok",
    "lastDataUpdatedDate": "31/10/2024"
    "totalResults": 500,
    "pageNumber":0,
    "pageSize": 50,
    "result": [
          {
            "companyNumber": "SC005832",
            "title": "JAMES JONES & SONS LIMITED",
            "companyStatus": "Active",
            "companyIncorporated": "31/03/1905",
            "companyRegisteredAddress": "BROOMAGE AVENUE,LARBERT,FK5 4NQ",
            "resultNumber": 0,
            "turnover": 603067.0,
            "netAssetsLiabilities": 555262.0,
            "cash": 162740.0,
            "totalAssetsLessCurrentLiabilities": 589724.0,
            "employees": 2132.0
        },
        {
            "companyNumber": "00115703",
            "title": "SOCIETY OF GENEALOGISTS(THE)",
            "companyStatus": "Active",
            "companyIncorporated": "08/05/1911",
            "companyRegisteredAddress": "UNIT 2,40 WHARF ROAD,LONDON,N1 7GS",
            "resultNumber": 1,
            "turnover": 682223.0,
            "netAssetsLiabilities": 3540978.0,
            "cash": 486287.0,
            "totalAssetsLessCurrentLiabilities": 3540978.0,
            "employees": 16.0
        },
        {
            "companyNumber": "00149058",
            "title": "ASH & LACY BUILDING SYSTEMS LIMITED",
            "companyStatus": "Active",
            "companyIncorporated": "05/12/1917",
            "companyRegisteredAddress": "ASH & LACY HOUSE,ALMA STREET,SMETHWICK,B66 2RL",
            "resultNumber": 2,
            "turnover": 647808.0,
            "netAssetsLiabilities": 3546760.0,
            "cash": 119789.0,
            "totalAssetsLessCurrentLiabilities": 3900545.0,
            "employees": 125.0
        }
    ]
}

Response Properties

Name Type Nullable Description
status
 string no Contains
Ok
if the request was successful,
Error
if there was an error.
lastDataUpdatedDate
 string no The date for the current dataset. This data is updated about once every four weeks.
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
totalAssetsLessCurrentLiabilities
 float yes Latest total Assets Less Current Liabilities figure , when available
turnOver
 float yes Latest Turnover figure, when available
cash
 float yes Latest Cash at hand/at bank figure , when available
employees
 integer yes Latest average number of employes figure , when available
resultNumber
 integer no Search results position for this company