Hi, just need to understand if the Company Profile API is suitable to meet the following requirements, and if our assumption re: endpoints and data fields is correct? Any guidance on the questions noted would also be hugely appreciated, thanks so much!
BR01. Check if company exists
Endpoint = /company/{number}; data field = http status code
Question: Our assumption is that 200 response = company exists; 404 response = company does not exist
BR02a. Check if company is UK registered
Endpoint = /company/{number} â jurisdiction; data field = jurisdiction
Question: Does âunited-kingdomâ refer to only mainland nations (and only for âenglandâ, an example we saw?), or also include Crown dependencies, BFPOs, or overseas territories?
BR02b. Check company is registered to a UK address
Endpoint = /company/{number} â registered_office_address.country; data field = registered_office_address / country
Question 1: Is there no country code? Do we simply string check for country field and if valid postcode etc.
Question 2: Could a UK-registered company ever have a non-UK registered address?
Question 3: We saw an example of an english address where âcountryâ: âUnited Kingdomâ - what is the guidance on this please?
BR03. Check company is a limited company
Endpoint = GET /company/{company_number}; data field = type
Question: Is âltdâ the only valid response for a genuinely limited company?
BR04. Check if company is active
Endpoint = /company/{number}; data field = company_status
Question 1: Is âactiveâ the only valid response to confirm company is indeed active
Question 2: If âactiveâ, will âhas_insolvency_historyâ always be false?
Donât have time to go point by point on these, but you would probably find the following helpful: https://github.com/companieshouse/api-enumerations, specifically constants.yml, this file contains enumerations for possible values for some of the fields you are asking about (jurisdiction, company type and status etc).
Generally: caution is advised. Companies House presents a very large dataset, which has been gathered over a long time (in some cases over 100 yearsâŚ)
Further - by law Companies House essentially has to record what the members of the public supply. But it seems that even where it might be reasonable to do so they donât always do a great deal of validation.
All that means that some fields can have all kinds of unexpected data - and in general âbeware what you donât knowâ.
As @ash notes - where the API returns one of their âenum constantsâ the data should be as advertised. But that doesnât include fields like address fields, or peopleâs names etc.
The best way to interrogate the data is probably just to try using it and see what you get.
However you can also find bulk data at:
⌠albeit this is in a different format to what you can get from the API and you donât get all the information you do in the API. Documentation for that is in the specs (for some unknown reason this box refuses to accept words or URLs containing part of the word dev*eloper so I canât post a link - just search!)
There are other bulk datasets - for officers you have to apply to Companies House directly though).
Questions:
Check if company is UK registered? You may have two questions / categories to decide: is this a âcompanyâ? Via the API Companies House records entities other than âcompaniesâ - youâll find a small zoo of âsocietiesâ and âassociationsâ, financial institutions, charities (see e.g. the âenum constantsâ and the company_type)⌠Then: âUK registeredâ: some data for foreign-registered entities is recorded also where they have UK branches. Thatâs reflected in the company ânumberâ - you have âFCâŚâ foreign companies and their related âBRâŚâ UK Branch(es). There are also some EU-related entities.
I am not sure how jurisdiction relates to Crown dependencies, BFPOs, or overseas territories however.
For the question about addresses - the address fields are some of those which donât seem to be parsed/validated, so I believe thatâs just down to us users to do.
As for whether a UK company could have a non-UK registered address? I am not certain they all will be (again - on us to check) but the current rules suggest so for a private limited company at least:
An example of things the other way round would be the âFCâŚâ - âBRâŚâ pairing (though the âBRâ would presumably always have a UK address, by definition).
Limited companies - see the Company Profile documentation again.
⌠and the âenumeration constantsâ. This possibly comes down to how you want to slice and dice things. Companies House records things like âltdâ (private limited company), âplcâ (public limited company), and differentiates things like âPrivate Limited Company by guarantee without share capital use of âLimitedâ exemption", âPrivate company limited by guarantee without share capitalâ etc. Thatâs without getting into other types like partnerships etc.
Active: see the company_status and company_status_detail fields. Again - this is partly âwhat do you class as active?â also.
As for insolvency - thatâs another area. I am not certain, but I seem to recall something from Companies House posted here regarding how those values changed as e.g. a company became solvent / was restarted etc. See:
Eventually the ultimate arbiter of these things are the actual filings the company has made⌠which may not be very helpful for a âmassâ query! Fortunately most companies are recent, and most are pretty simple affairs.