If you check the http response code you get back, you will likely be getting a 404 (not found), is that true?
In fact you’ll get this for almost all companies (note 1). Most companies don’t have their registers held by Companies House, so this response is “correct” e.g. there are none found.
So you should either expect this (most of the time) and trap it, or you could call the Company Registers end point first. If there are registers held in public this will provide more information - including the links to this information via the Officers endpoint.
Example of a random company with this information:
Note1: While Companies House maintains a registry of information available to the public most private companies maintain their own private registers (the registers required by law) with full details of information required by statute:
Register of members, Register of persons with significant control, register of directors, register of directors’ usual residential addresses and register of company secretaries.
Only a few choose to have this information held on the public register - as doing so means the full details e.g. full dates of birth and home addresses are public.
Ah - if you’re just interested in “active” or not then I suggest that you don’t send the register_view parameter at all - that has nothing to do with officers being active.
Unfortunately the API does not have the functionality to filter by officer status (active / resigned).
You will have to filter the results yourself in your code.
This functionality has been requested from Companies House e.g. see this thread:
I was trying to explain last time that this is reasonable behaviour for communicating via http (albeit some APIs don’t follow this convention…). If you ask for something and it is not found (doesn’t exist) then you might expect a 404 not found [http response code](http response code) (and in this case no http body). If you ask for something that does exist you get a 200 response code and - if there is any - the data in the http body.
switching on register_view will only provide a small amount of extra information (dates of birth, possibly addresses) for a tiny subset of companies. Unless you are very specifically interested in this I suggest you ignore this entirely e.g. do not set the register_view parameter. (If you don’t supply it this is the same as register_view=false).
if you do want this information (again - very rare to find it unless you know in advance the company is one of the few where they have opted to do this) then handle a 404 not found response code when this data isn’t present. (Presumably you would then call again with the same parameters except register_view=false to just get the data Companies House has).
Another strategy would be to first request the Company Profile for the company: the links member of this resource should give you a registers member with the appropriate link if the company does have some registers held by Companies House e.g. public - in the example this would be “/company/09446118/registers”.
Companies which don’t have this information shouldn’t have this link.
We don’t rely completely on the presence or absence of links however - in general we try to avoid making assumptions with this API as many have proved not to be true for all situations!
|egister_view|string|Display register specific information. If given register is held at Companies House, registers_view set to true and correct register_type specified, only active officers will be returned. Those will also have full date of birth.Defaults to false
If the company is one of the rare ones where Companies House hold their (directors / secretaries) registers AND you have specifically requested the data from those (with register_view=true), they are saying they will only return the active ones.
So effectively you can either request:
a) Officers information - “standard mode” (don’t specify register_view OR specify it and set it to false) - will show active and resigned officers, all of them (you have to filter that yourself if you only want active ones). It works (I believe) the same for any company. (Note - further detail - there are entities that Companies House returns some information e.g. a “Company Profile” but where there are no “officers” or Companies House doesn’t record them - examples are charitable incorporated and Royal Charter Companies I think).
b) Full information from public registers (basically same as above plus maybe day of birth as well as month and year, and maybe the officer’s residential address as opposed to their “service address” which is normally the company’s offices) - set register_view=true. These don’t exist for most companies so you’ll almost always get a 404 not found response. For the few companies where this exists you get the data but ONLY on the current active officers.
Don’t ask me why Companies House API is designed this way - but I believe that is how it is. If you find something different please post it so the rest of us can learn!
On your last point - there’s clearly something that I don’t understand about what you are trying to do. What is an “etag query” - and why would you be doing that?
If you just want all the active officers, as I’ve said just request e.g.:
… then loop over each member of the items array that is returned - apply any sort or filter you need then e.g. remove any with a resigned_on member (should be a date).
I believe I’ve suggested a way to do what you seemed to be asking (“I am trying to filter only active as it reads in the documentation”) - or rather I’ve pointed out that the API doesn’t have a general way to do that. I hope I have explained what the documentation means and the “special case” where you only get active officers.
BUT I’m not Companies House. I’ve just stated how it works for us and the way I understand it. If that’s not helpful for you to understand the API feel free to ignore it. If you feel the API should work a different way, feel free to ask Companies House to change it. (They don’t change things very often…)
There’s nothing that’s an “error” in my view here. The API does have bugs or “features” elsewhere - but you haven’t shown one here. When using it you do have to understand something of the nature of UK Companies Regulations and how that is expressed in the data set AND something about REST APIs / http conventions (and the latter two aren’t entirely settled anyway…)
Again if I have misunderstood what you’re trying to do (the big picture is always helpful…) or you have discovered a specific error do post it. For the latter it’s useful to post the whole URL you’re requesting and the http response status code AND any http body you get. Other information is always helpful e.g. confirm you’re using a “live” application and not the test / sandbox, confirm it’s a “GET” request not e.g. POST (I think the Public Data API always expects GET anyway). In many cases the “problem” seems to be misunderstandings about the language / tool / library being used - so it may be helpful to list that e.g. “using fetch( ) in javascript with the following arguments…” Just be sure NOT to post your API key / any sensitive information.
Yes - and the resigned_on fields is available in both the Officer Appointment resource and the Officers list.
For most uses there should be no need to e.g. request the officers list AND then the Officers Appointments (or vice versa) as most if not all of the fields for each officer are in both results. (Obviously you might have a use case where e.g. you were working from the Officer Appointments list and wanted to find all the other officers in a given company OR the opposite).