Questions regarding your api from lovely austria :-)

API Question
#1

Hello.

I’am a developer from austria who wants to integrate companies house api. I do have a couple of questions regarding
your data model. I noticed that the documentation is out of date for some pages, therefore I contact you.

Question 1:

api/reference/officers/list

What are valid queryParams ? I always do get an error when I try to use ‘register_view’ query Param.

Question 2:

For testing purposes: Can you please send me companynumbers to test the following endpoints : ?
api/reference/officers/list
api/reference/registers/company-registers
api/reference/exemptions/get

Question 3:

For below Items, can you please send me the possible values ? Or the reference to the enums you use ? It is missing in the docu!

developer-specs.company-information.service.gov.uk/companies-house-public-data-api/resources/officerlist?v=latest

items[].address.country
items[].address.locality
items[].country_of_residence
items[].nationality

Question 4:

Is there a possiblity to get notified in advance when you change the api ?

1 Like
#2

With regards to Question 3, I suspect a lot of those fields cannot be enumerated as they can expose data that was submitted under a variety of different systems (including those that considerably predate any form of electronic submission and storage), with different degrees of validation (including free text with no validation) and include countries that are disputed or no longer exist etc.

Currently if you want to incorporate a company you submit:

Country as the three letter ISO code
Country of Residence is free text
Nationality from this list: Nationalities and countries for company filings - GOV.UK (which is relatively new, up until recently this was free text)
Locality I don’t think I’ve ever seen used and I don’t think is part of currently submitted forms. Possibly a legacy field from an older system?

From experience: If you’re dealing with historical companies you just need to treat addresses as a block of text. If you are only dealing with recent companies you probably need to look at how the data is submitted as that will dictate the possible values.

^^^^ This is all unofficial and just based on my own experiences working with addresses.

VVVV Some useful links if you are looking at recent companies:

https://xmlgw.companieshouse.gov.uk/
http://xmlgw.companieshouse.gov.uk/SchemaStatus

#3

Further to what @ash said (also noting this is just from our own experience e.g. not official) - first 3 questions (last one is for Companies House):

Question 1:

api/reference/officers/list

What are valid queryParams ? I always do get an error when I try to use ‘register_view’ query Param.

I think the documentation is correct as far as it goes (but it could be more helpful!) but when you use the officers endpoint and request registers you:
(a) you need to pass both register_view=true and a register_type parameter e.g. https://api.companieshouse.gov.uk/company/09446118/officers?register_view=true&register_type=directors
If you just send the parameter register_view=true you’ll get a 400 Bad request.
If you request registers which are not stored you may get the data error (JSON):
{ "errors" : [ { "type" : "ch:service", "error" : "not-on-public-register" } ] }

Our process for getting this would be:
i) Request the company profile and check the “links” member in the response - if there’s a registers member then these should be available.
ii) Find out which registers are held by Companies House by requesting the registers endpoint. As per the documentation that structure will tell you what is held. Translate this into whether there is directors, secretaries or LLP members data.
iii) Request the appropriate register information (directors, secretaries or llp-members) using the officers list endpoint e.g. passing this in the register_type parameter:
/company/SC609220/officers?register_view=true&register_type=directors

(b) In your next question you ask for examples. This is necessary since there are only a few companies where Companies House keeps the registers - so the chance of finding one of these at random is not high. So in general it’s rare that this extended information (e.g. full address / birth date) is available.

For more information on this subject (in case you’re not familiar with this already) see:

Question 2:
For testing purposes: Can you please send me companynumbers to test the following endpoints : ?
api/reference/officers/list
api/reference/registers/company-registers
api/reference/exemptions/get

Companies House don’t generally seem to maintain lists of examples. This is presumably since (a) these would need to be maintained and (b) there might be other reasons for not “picking out” certain companies. Ones that I’ve come across are:

Registers: 09446118, SC609220
Exemptions: 00048839, 00502851

When you ask for examples of the officers list this becomes a little more difficult. We’ve collected a “zoo” of examples of different features over time but it depends on what you are interested in learning about. Again, as @ash mentioned there’s little consistency here - especially in older data. One thing you can do is register for the bulk officer data in the following thread and then you can explore this yourself.

Since the PSCs share a lot of the officer data format you can also download the bulk PSC lists to analyse them yourself.

Question 3:

For below Items, can you please send me the possible values ? Or the reference to the enums you use ? It is missing in the docu!

developer-specs.company-information.service.gov.uk/companies-house-public-data-api/resources/officerlist?v=latest 1

@ash answered this - when we process this information we essentially treat these as “free text” fields. Certainly for older data there appear to be no guarantees of what you may find here or indeed whether these will contain anything. I believe the documentation still states these fields are optional - which is generally a warning not to rely on it in any way!

#4

Your responses were really helpful, thank you !!

So i stick to the approach of handling the data as free text.

Have a nice day,

Reinhard.

#5

I do have another question :slight_smile:

@Registers

“usual_residential_address”: {
“items”: [
{
“moved_on”: “2017-02-20”,
“register_moved_to”: “public-register”
}
],

what does it mean “register_moved_to” ? is the information about the “usual_residential_address”
not available anymore ? What is included in those fields ?

In general where can I find a documentation about the
api. I mean about the context of the api, not about the fields ? Its quite difficult to have an understanding of the api without documentation. Can you please reference me the relevant docu. I’m sure there is one, but I just dont know where it is.

I also would like to test the “charges” endpoint but dont have a companyNumber to test with. Maybe you can provide me one as well.

many thanks in advance,

Have a nice day,

Greetings,

Reinhard.

#6

Not sure about the first one. The “context” of a lot of this isn’t well documented and assumes a knowledge of UK company structures/law. That said one of the things I found most useful is the fact that Companies House’ forward facing company search facility use the same API so when you encounter something you’re not sure about in the returned data, if you look the same company up in their search you can often deduce context/meaning based on how they render the same data:

With regards to charges they’re pretty common, I’ve used British Airways in the past, they have hundreds: BRITISH AIRWAYS PLC - Charges (free information from Companies House)

#7

what does it mean “register_moved_to” ? is the information about the “usual_residential_address”
not available anymore ? What is included in those fields ?

I agree - the main registers documentation doesn’t give context.

I find it helps to remember that this all started - and indeed can still be done - on paper forms. So think of the database as being pulled from a set of paper documents. “Updates” of some kind imply “we received another form”. I’ll refer to this below.

From the English Wikipedia page for Companies House:

…private companies can elect to keep certain statutory records on the central register which is held and published by Companies House, instead of maintaining their own registers. These records include:
Register of members
Register of people with significant control
Register of directors
Register of directors’ usual residential addresses
Register of secretaries

The “Register of directors’ usual residential addresses” is of interest because the default for all addresses that are available publicly via the API is for them to be a “service address”. This could be the person’s residential address but it is almost always a company’s address, normally the registered office address.

As I understand the process (and I am not an expert): a company is required to keep and maintain registers (lists) of the information mentioned above. The company must also inform Companies House where this information is. The vast majority of companies maintain these lists at their company registered office address. This is the “default” situation - and in that case you won’t normally get any “registers” member from the API I think. However at some point (possibly from when the company is first registered) a company can instead ask Companies House to keep some or all of these lists. If this happens the list is on “the public register”. Companies House will then have a registers record available via the API. That register’s register_moved_to field will be public-register and the moved_on field will be the date that Companies House got this. So you can think of this as a physical “movement” or “transfer” of this list to Companies House.

If a company later removed the information from the public register I’m not sure what happens. I would guess that there would still be a registers record and that this would have an extra entry in the registers member with the date in moved_on and where these went in register_moved_to. I do not know if the original record (e.g. register_moved_to with public-register) would remain.

Have a look - if you can bear it - at the form to register a company. This is Form IN01 and in Part 6 you’ll find “Election to keep information on the public register (if applicable)”. Hopefully looking at that and the director, secretary and PSC sections above you’ll be able to see what data is collected and thus where these fields come from.

There are other effects that occur as well. Depending on what registers are “moved” to Companies House the data sets available (e.g. for directors, secretaries, PSCs) may then show extra information. In the case of the officers list you need to pass in the “registers view” parameters as described above to get this. You may see the actual home / residential address of directors, and / or full dates of birth (with day of the month).

Again this is not hugely useful generally if you want “extra data” since most companies will keep this at their registered office from the start. So Companies House will actually know this (they receive it on e.g. the initial company registration form) but it isn’t made publicly available.

I agree with @ash - most of the API is of limited use unless you understand the context. I did not have this knowledge although our company has others with specific expertise in areas of this. What I found useful was:

The actual forms that are used to communicate with Companies House - so you can clearly see what data is required and get a feel for just how “fuzzy” this is going to be (and see why certain “mistakes” are very common).
Companies House blog (for announcements and some context)
A document giving information about the registrar - more “context”

If you really want detail then UK legislation is available online.

#8

Thank you !

Maybe you can answer me one more question:

I checked the companyProfile and did not find information about :

  • Website
  • Email
  • phone number
  • tax id / sales tax identification number
  • register date of the company
  • deliveryAddress

And how do I get the excerpt from the company register eg:

" Proof submitted in original or authenticated form, confirming that the bareboat charter company is a legally existing company, including, inter alia, the business relationships (shareholders/directors) and the persons having power of representation and their legitimation along with an excerpt from the company register."

Is this possible to get this document via the api ? If not , how do I get that document. I only found the “filing-history” endpoint which points to various documents but that is not what is needed I guess.

Thank you so much again in advance,

Greetings from austria!

#9

You’re correct - if you don’t see it, you don’t get it!
As far as I know the API won’t have any of the items on your list. Not even the “tax id / sales tax identification number” - which I believe would translate to the “VAT number”.

As for legally proving that the company is an existing legitimate entity and the details are correct - this is something we have explored. Of course this entirely depends upon “who is asking and why” e.g. what is the purpose, what are the rules you’re being judged by, what is acceptable as proof under those regulations etc. From what I understand in the UK legislation there is no longer a “single document” which shows the state of a company at the moment. I believe the Companies House register - e.g. the data they hold / what is available on their site / via the API - constitutes “the record” at a particular moment. Check with your lawyers though!

Another point is that - by the laws that apply here - different rules apply to different entity types. So depending on the entity type different situations will trigger reporting, different forms are submitted on different occasions and different data is required.

You could do something like the following:

  • Take a “snapshot” of the current API data for the company (company profile, officers, PSCs, charges etc.)

  • Many rules require obtaining the original main “foundation” documents e.g. “Incorporation”, “Memorandum and Articles of Association”. To do that you can use the filing history list to check for the “incorporation” value in the “category” field. (It may also be wise to check for a range of specific form types in the “type” parameter - it was the case a few years ago that not everything had the “category” field as expected).

  • There are documents which must be filed regularly (e.g. yearly) that relate to the “status” of a company. These are the Accounts and the Confirmation Statement. Some years back the key document was the Annual Return rather than the Confirmation Statement. This was useful because it actually gave the “state” of the company and had some useful information that is less easy to obtain now e.g. shareholders / shareholdings. These were replaced by the Confirmation Statement however. The Confirmation Statement either records “the information Companies House has now is correct” or “there have been changes since the last Confirmation Statement and these are …”.

  • You may be required to provide documentation of “fundamental changes” to the company e.g. change of name, change of purpose, change of “type” (for example from a private limited company to a public limited company). One way to do that is by working through the filing history to check for any key “change to company” documents occurring after the incorporation e.g. the categories “change-of-name”, “change-of-articles”. Obviously there are some details to work out as certain things can be recorded as resolutions which may be important to you. (I believe articles and name changes should always trigger a filing of the appropriate category though). You may also want to avoid going through the entire filing history list which can be very extensive for some companies!

Checking the other information
You’re best to Google for that / use another service. Googling will show some methods you could use to obtain and check e.g. the VAT number etc.

As for seeing what information is actually available via the API you could:

Good luck.