/api/lists/getlistdata

This API endpoint returns companies within a list. The data currently includes key financial and other company data shown in search results but in future versions all available data available using /Financials will be added.

Lists Version 2

Version and Endpoint

Only available in API version 2

Request

GET https://convert-ixbrl.co.uk/api/lists/getlistdata?listname=YourListName&apiversion=2

This endpoint requires authentication headers. See Authentication documentation.

Method Type

HTTP GET

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 2)
listName	string	No	Name of the list. For lists with spaces in the name, URL-encode the name by replacing each space with %20. For example, My List would become My%20List

HTTP Response codes

Status Code	Description
`200`	Successful requests with results
`404`	Returned when the specified list name was not found
`400`	Authorisation error for when the secret key header is missing or is invalid

Response JSON Sample (only one company shown for brevity)

The order of fields may be different to what is shown below

{
    "status": "Ok",
    "results": [
        {
           
            "companyNumber": "12345678",
            "title": "EXAMPLE COMPANY LIMITED",
            "companyStatus": "Active",
            "companyIncorporated": "23/04/1975",
            "companyRegisteredAddress": "FULL ADDRESS HERE",
            "regAddressCareOf": "",
            "regAddressPOBox": "",
            "regAddressLine1": "FIRST LINE OF ADDRESS",
            "regAddressLine2": "HOLBORN",
            "regAddressCounty": "",
            "regAddressPostTown": "LONDON",
            "regAddressCountry": "ENGLAND",
            "cashBankOnHandPrev1": 205825.0,
            "cashBankOnHandPrev1Year": 2022,
            "cashBankOnHandPrev2": 508825.0,
            "cashBankOnHandPrev2Year": 2021,
            "totalAssetsYear": null,
            "turnover": 14146063.0,
            "turnoverYear": 2023,
            "turnoverPrev1": 15556486.0,
            "turnoverPrev1Year": 2022,
            "turnoverPrev2": 13314746.0,
            "turnoverPrev2Year": 2021,
            "netAssetsLiabilities": 10621061.0,
            "netAssetsLiabilitiesYear": 2023,
            "netAssetsLiabilitiesPrev1": 9488382.0,
            "netAssetsLiabilitiesPrev1Year": 2022,
            "netAssetsLiabilitiesPrev2": 8493940.0,
            "netAssetsLiabilitiesPrev2Year": 2021,
            "cash": 335937.0,
            "cashBankOnHandYear": 2023,
            "totalAssets": null,
            "totalAssetsPrev1": null,
            "totalAssetsPrev1Year": null,
            "totalAssetsPrev2": null,
            "totalAssetsPrev2Year": null,
            "totalLiabilities": null,
            "totalLiabilitiesYear": null,
            "totalLiabilitiesPrev1": null,
            "totalLiabilitiesPrev1Year": null,
            "totalLiabilitiesPrev2": null,
            "totalLiabilitiesPrev2Year": null,
            "totalAssetsLessCurrentLiabilities": 10829533.0,
            "totalAssetsLessCurrentLiabilitiesYear": 2023,
            "totalAssetsLessCurrentLiabilitiesPrev1": 10056649.0,
            "totalAssetsLessCurrentLiabilitiesYearPrev1Year": 2022,
            "totalAssetsLessCurrentLiabilitiesPrev2": 9085733.0,
            "totalAssetsLessCurrentLiabilitiesYearPrev2Year": 2021,
            "averageNumberEmployeesDuringPeriod": 100,
            "averageNumberEmployeesDuringPeriodYear": 2023,
            "averageNumberEmployeesDuringPeriodPrev1": 84,
            "averageNumberEmployeesDuringPeriodPrev1Year": 2022,
            "averageNumberEmployeesDuringPeriodPrev2": 73,
            "averageNumberEmployeesDuringPeriodPrev2Year": 2021,
            "sicCode1": "71111",
            "sicCode1Text": "Architectural activities",
            "sicCode2": "",
            "sicCode2Text": "",
            "sicCode3": "",
            "sicCode3Text": "",
            "sicCode4": "",
            "sicCode4Text": "",
            "accountsDueDate": "30/09/2025",
            "accountsOverDue": false,
            "cs01DueDate": "28/07/2025",
            "cs01OverDue": false,
            "yearEnd": 2023, 
            "resultNumber": 1,
            "otherCompaniesAtAddress": 37,
            "company_financial_list": []
        }
    ],
    "errorMessage": null
}

Response Properties

Name	Type	Nullable	Description
status	string	no	Contains Ok if the request was successful, Error if there was an error.
errorMessage	string	yes	If the request was unsuccessful, this would contain a description of the error where available
result	object	no	Contains company details and key financial data. Note that this does not include all the financial fields that are sent across in response to a call to /financials

Response properties for result object

Name	Type	Nullable	Description
companyNumber	string	no	The company's registration number.
title	string	no	The full legal name of the company.
companyStatus	string	no	The current status of the company (e.g., "Active").
companyIncorporated	string	no	The date when the company was incorporated (e.g., "23/04/1975").
companyRegisteredAddress	string	no	The full registered address of the company.
regAddressCareOf	string	yes	Care of address.
regAddressPOBox	string	yes	PO Box address.
regAddressLine1	string	yes	First line of the registered address.
regAddressLine2	string	yes	Second line of the registered address.
regAddressCounty	string	yes	County of the registered address.
regAddressPostTown	string	yes	Post town of the registered address.
regAddressCountry	string	yes	Country of the registered address.
cashBankOnHandPrev1	number	yes	Cash/Bank on hand for the previous year -1. Note that the two might not be consecutive.
cashBankOnHandPrev1Year	integer	yes	Year for cashBankOnHandPrev1.
cashBankOnHandPrev2	number	yes	Cash/Bank on hand for the previous year -2. Note that the two might not be consecutive.
cashBankOnHandPrev2Year	integer	yes	Year for cashBankOnHandPrev2.
totalAssetsYear	integer	yes	Year for total assets.
turnover	number	yes	The company's turnover for the current year.
turnoverYear	integer	yes	The year for which the turnover is reported.
turnoverPrev1	number	yes	Turnover for the previous year -1. Note that the two might not be consecutive.
turnoverPrev1Year	integer	yes	The year for turnoverPrev1.
turnoverPrev2	number	yes	Turnover for the previous year -2. Note that the two might not be consecutive.
turnoverPrev2Year	integer	yes	The year for turnoverPrev2.
netAssetsLiabilities	number	yes	The company's net assets or liabilities for the current year.
netAssetsLiabilitiesYear	integer	yes	The year for netAssetsLiabilities.
netAssetsLiabilitiesPrev1	number	yes	Net assets/liabilities for the previous year -1. Note that the two might not be consecutive.
netAssetsLiabilitiesPrev1Year	integer	yes	The year for netAssetsLiabilitiesPrev1.
netAssetsLiabilitiesPrev2	number	yes	Net assets/liabilities for the previous year -2. Note that the two might not be consecutive.
netAssetsLiabilitiesPrev2Year	integer	yes	The year for netAssetsLiabilitiesPrev2.
cash	number	yes	Cash on hand.
cashBankOnHandYear	integer	yes	Year for cash on hand.
totalAssets	number	yes	Total assets.
totalAssetsPrev1	number	yes	Total assets for the previous year - 1. Note that the two might not be consecutive..
totalAssetsPrev1Year	integer	yes	Year for totalAssetsPrev1.
totalAssetsPrev2	number	yes	Total assets for the previous year - 2. Note that the two might not be consecutive..
totalAssetsPrev2Year	integer	yes	Year for totalAssetsPrev2
totalLiabilities	number	yes	Total liabilities.
totalLiabilitiesYear	integer	yes	Year for total liabilities.
totalLiabilitiesPrev1	number	yes	Total liabilities for the previous year -1. Note that the two might not be consecutive.
totalLiabilitiesPrev1Year	integer	yes	Year for totalLiabilitiesPrev1.
totalLiabilitiesPrev2	number	yes	Total liabilities for the previous year -2. Note that the two might not be consecutive.
totalLiabilitiesPrev2Year	integer	yes	Year for totalLiabilitiesPrev2.
totalAssetsLessCurrentLiabilities	number	yes	Total assets less current liabilities.
totalAssetsLessCurrentLiabilitiesYear	integer	yes	Year for total assets less current liabilities.
totalAssetsLessCurrentLiabilitiesPrev1	number	yes	Total assets less current liabilities for the previous year - 1. Note that the two might not be consecutive..
totalAssetsLessCurrentLiabilitiesYearPrev1Year	integer	yes	Year for totalAssetsLessCurrentLiabilitiesPrev1.
totalAssetsLessCurrentLiabilitiesPrev2	number	yes	Total assets less current liabilities for the previous year - 2. Note that the two might not be consecutive..
totalAssetsLessCurrentLiabilitiesYearPrev2Year	integer	yes	Year for totalAssetsLessCurrentLiabilitiesPrev2.
averageNumberEmployeesDuringPeriod	integer	yes	Average number of employees during the period.
averageNumberEmployeesDuringPeriodYear	integer	yes	Year for averageNumberEmployeesDuringPeriod.
averageNumberEmployeesDuringPeriodPrev1	integer	yes	Average number of employees during the period for the previous year - 1. Note that the two might not be consecutive..
averageNumberEmployeesDuringPeriodPrev1Year	integer	yes	Year for averageNumberEmployeesDuringPeriodPrev1.
averageNumberEmployeesDuringPeriodPrev2	integer	yes	Average number of employees during the period for the previous year - 2. Note that the two might not be consecutive..
averageNumberEmployeesDuringPeriodPrev2Year	integer	yes	Year for averageNumberEmployeesDuringPeriodPrev2.
sicCode1	string	yes	Standard Industrial Classification code 1. Reference list: `/Documentation/v2/SicCodes`.
sicCode1Text	string	yes	Description of Standard Industrial Classification code 1.
sicCode2	string	yes	Standard Industrial Classification code 2(if in use by the company).
sicCode2Text	string	yes	Description of Standard Industrial Classification code 2(if in use by the company).
sicCode3	string	yes	Standard Industrial Classification code 3(if in use by the company).
sicCode3Text	string	yes	Description of Standard Industrial Classification code 3(if in use by the company).
sicCode4	string	yes	Standard Industrial Classification code 4(if in use by the company).
sicCode4Text	string	yes	Description of Standard Industrial Classification code 4(if in use by the company).
accountsDueDate	string	yes	The due date for the company's accounts.
accountsOverDue	boolean	yes	Indicates whether the company's accounts are overdue.
cs01DueDate	string	yes	The due date for the company's Confirmation Statement.
cs01OverDue	boolean	yes	Indicates whether the company's Confirmation Statement is overdue.
yearEnd	integer	yes	Year for the values reported. Note that certain values such as turnover have the year of report specified as a separate property because turnover is not reported every year.
resultNumber	integer	yes	Result number, starting at 0.
otherCompaniesAtAddress	integer	yes	Number of other companies at the same address.
company_financial_list	array	yes	Not populated in this version of the API. When available, this will be an array where each element contains financial data for a single year. It is the same object as the result.company_financial_list array returned by /GetFinancials.