/api/lists/getlistdata

This API endpoint returns the companies in a list. For each company it returns the company details, key financial figures, and the full financial statements (the same company_financial_list that /Financials returns) for companies that have filed financial data. Everything is read from our latest data every time the list is called, so you always get current values.

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.

Credits and response size

This endpoint works like /Financials for every company in the list. Each call uses 1 credit for each company that has financial data, every time you call it, including repeat calls. A company with no financial data uses no credits. Companies with no statements at all are returned with an empty company_financial_list.

If your balance is lower than the credits needed, the call returns 402 and no data. A list can hold up to 2,000 companies, so the response can be large (roughly 20 KB per company with full statements). Send the Accept-Encoding: gzip header to receive it compressed, which is about ten times smaller.

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
`402`	Insufficient credits to return the list. No data is returned and no credits are used.
`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",
            "regAddressPostCode": "EC1N 2XX",
            "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": [
               {
              "end_date": "31/03/2024",
              "profit_loss": {
                "turnover": "4500000.0",
                "cost_of_sales": "1800000.0",
                "administrative_expenses": "800000.0",
                "distribution_costs": "250000.0",
                "gross_profit_loss": "2700000.0",
                "operating_profit_loss": "1650000.0",
                "audit_fees": "30000.0",
                "profit_loss": "1200000.0",
                "retained_profits": "1756204.0",
                "salaries": "600000.0",
                "other_operating_income": "150000.0",
                "other_interest_receivable_and_similar_income_finance_income": null,
                "interest_payable_and_similar_charges_finance_costs": "50000.0",
                "profit_loss_on_ordinary_activities_before_tax": "1600000.0",
                "tax_taxcredit_on_profit_or_loss_on_ordinary_activites": "400000.0",
                "depreciation_expense_property_plant_equipment": "100000.0",
                "comprehensive_income_expense": null
              },
              "balance_sheet": {
                "fixed_assets": "11556379.0",
                "intangible_assets": null,
                "investments": "11556379.0",
                "investments_fixed_assets": "11556379.0",
                "investment_property": null,
                "investment_property_fair_value_model": null,
                "investments_in_subsidiaries": null,
                "investments_in_group_undertakings": null,
                "investments_in_group_undertakings_participating_interests": null,
                "investments_in_subsidiaries_measured_fair_value": null,
                "investments_in_joint_ventures": null,
                "investments_in_associates": null,
                "other_investments_other_than_loans": null,
                "disposals_investment_property_fair_value_model": null,
                "current_assets": "337540.0",
                "current_asset_investments": null,
                "stock": "125000.0",
                "debtors_amounts_falling_due_current": "0.0",
                "trade_debtors_amounts_falling_due_current": "112000.0",
                "debtors_amounts_falling_due_non_current": null,
                "trade_debtors_amounts_falling_due_non_current": null,
                "cash": "337540.0",
                "total_assets": "11893919.0",
                "liabilities": "434515.0",
                "creditors_amounts_falling_due_current": "137110.0",
                "trade_creditors_trade_payables_due_current": "90000.0",
                "net_current_assets_liabilities": "200430.0",
                "creditors_amounts_falling_due_non_current": "297405.0",
                "trade_creditors_trade_payables_due_non_current": null,
                "total_borrowings": "250000.0",
                "loans_from_directors": "120000.0",
                "bank_overdrafts": null,
                "bank_overdrafts_current": null,
                "bank_overdrafts_non_current": null,
                "accrued_liabilities": "55000.0",
                "government_grants_payable": null,
                "unpaid_contributions_to_pension_schemes_current": null,
                "unpaid_contributions_to_pension_schemes_non_current": null,
                "total_assets_less_current_liabilities": "11756809.0",
                "net_assets": "11456404.0",
                "shareholders_equity": "11456404.0",
                "calledup_share_capital": "9700000.0",
                "retained_earnings_accumulated_losses": "1756204.0"
              },
              "changes_in_equity": {
                "opening_retained_earnings_accumulated_losses": "555204.0",
                "retained_earnings_accumulated_losses": "1756204.0",
                "share_capital": "9700000.0",
                "profit_loss_affecting_equity": "1200000.0",
                "dividends_paid": null,
                "comprehensive_income_expense": null
              },
              "other_notes_to_financial_statements": {
                "employee_count": "3",
                "wages_and_salaries": "600000.0",
                "social_security_costs": "72000.0",
                "pension_costs_defined_contribution_plan": null,
                "pension_other_post_employment_benefit_costs_other_pension_costs": null,
                "audit_fees_expenses": "30000.0",
                "fees_for_non_audit_services": null,
                "government_grant_income": "50000.0",
                "government_grants_payable": null,
                "amount_specific_advance_or_credit_made_in_period_directors": null,
                "amount_specific_advance_or_credit_directors": null
              },
              "cash_flow": {
                "interest_expense_on_bank_overdrafts": null,
                "tax_taxcredit_on_profit_or_loss_on_ordinary_activites": "400000.0",
                "gain_loss_in_cash_flows_from_change_in_inventories": "-25000.0",
                "gain_loss_in_cash_flows_from_change_in_debtors_trade_other_receivables": "30000.0",
                "gain_loss_in_cash_flows_from_change_in_creditors_trade_other_payables": "-18000.0",
                "net_cash_generated_from_operations": "1450000.0",
                "income_taxes_paid_refund_classified_as_operating_activities": "380000.0",
                "net_cash_flows_from_used_in_operating_activities": "1070000.0",
                "purchase_property_plant_equipment": "250000.0",
                "proceeds_from_sales_property_plant_Equipment": null,
                "net_interest_received_paid_classified_as_investing_activities": null,
                "net_cash_flows_from_used_in_investing_activities": "-250000.0",
                "dividends_paid_classified_as_financing_activities": null,
                "net_cash_flows_from_used_in_financing_activities": "200000.0",
                "IncreaseDecreaseInCashCashEquivalentsBeforeForeignExchangeDifferencesChangesInConsolidation": "102000.0",
                "cash_bank_on_hand": "337540.0",
                "cash_bank_on_hand_at_beginning_of_year": "235540.0"
              }
            }
            ]
        }
    ],
    "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 the companies in the list: company details, key financial figures and, where the company has financial data, the full financial statements in company_financial_list.

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.
`regAddressPostCode`	string	yes	Postcode 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	An array where each element contains the full financial statements for a single year. It is the same object as the result.company_financial_list array returned by /Financials. It is an empty array for companies with no financial data.