API - Officers Appointment List

[mark.bowers]

I am looking through the list of the publicly available API’s from Companies House and more specifically the ‘Officer Appointments List.

The API needs the data item of ‘officer_id’ for it to return details but I cannot find the company related API that provides this data item.

Could you please let me know which of the API’s I need to use in order to have the ‘officer_id’ data item returned.

[voracityemail]

This one’s been asked and answered several times already but maybe the following summary helps?

The API is largely designed based on following a couple of “paths” through it. It sounds like you’re wanting to “look up appointments for an officer” - so you’ll either get to that point by:

1. Searching for an officer’s appointments (you have a name). Use the the Search Officers endpoint, passing the name string, to get back a list of officers. Each will have a link to the appointments endpoint in the links member.
2. Looking at the appointments of one or more officers of a particular company (you have a company name / number / details, and the API then allows you to look up the list of officers). This would typically be e.g. call Search Company (or the advanced search) with the company name or number to get the company profile data, pull the officers URL from the links member, call that to get the list of officers of the company. Each officer will have an officer.appointments member in the links member. Just request that to get the same information as in (1).

So it’s less a case of “knowing the ID” and more “follow the links to get a particular resource”. The API provides “links” (the path part of the URL) in responses. You get links to the appropriate “appointments list” when you request information about 1 or 2 above. Request the resource at the link and get what you need (e.g. concatenate the “https://api.company-information.service.gov.uk” address and the appropriate URL from links and request that).

Example of (1):

curl -u YOUR_API_KEY: "https://api.company-information.service.gov.uk/search/officers?q=gibson&items_per_page=2"
{
    "kind": "search#officers",
    "start_index": 0,
    "items": [
        {
            ...
            "links": {
                "self": "/officers/vcZz6vfqyrlqjUqezTzS7wa9rWM/appointments"
            },
        },
        {
            ...
            "links": {
                "self": "/officers/oxl3plrten8gcwyPxaMmQpnJH_I/appointments"
            },
        }
    ],
    "total_results": 13878,
    "items_per_page": 2,
    "page_number": 1
}

Example of (2):

curl -u YOUR_API_KEY: "https://api.company-information.service.gov.uk/company/OC329075"
{
    ...
    "links": {
        "self": "/company/OC329075",
        "filing_history": "/company/OC329075/filing-history",
        "officers": "/company/OC329075/officers",
        "persons_with_significant_control": "/company/OC329075/persons-with-significant-control"
    },
}

Then

curl -u YOUR_API_KEY: "https://api.company-information.service.gov.uk/company/OC329075/officers"
{
    ...
    "items": [
        {
            ...
            "links": {
                "officer": {
                    "appointments": "/officers/70Ct1FzNWUyVji7pWP9IYfC96Dk/appointments"
                },
                "self": "/company/OC329075/appointments/xPV4K5tXs88G4LsP1dbrfBEZ6gY"
            },
        ...
    ],
    ...
}

Then get the links.officer.appointments member.

[mark.bowers]

Thank you very much for your reply, very much appreciated.

The issue that example 1 has for us is that it would just return a name. I am then trying to match this to a list of names in our database and it could be impossible to marry the 2 together.

I am am looking to achieve is to return Company data based on individual company details to return Appointed Officer details. I am then looking to identify the Appointed Officer returned to ensure see if they have interests in other companies that could cause a conflict of interest.

Based on what I can see from the API’s, we can obtain the data from Companies House but none of the API’s provide the ‘officer ID’. We can check the name returned but we have the issue of ‘John Smith’ for example where it will be near impossible to marry the two together.

Any ideas please would be greatly appreciated

[voracityemail]

I’m still not understanding your issue.

@mark.bowers

I am am looking to achieve is to return Company data based on individual company details to return Appointed Officer details. I am then looking to identify the Appointed Officer returned to ensure see if they have interests in other companies that could cause a conflict of interest.

Take example 2:

1. You start with a company (either you have the company number already, or you search and find the company number from e.g. the company name).

2. You call the Officers endpoint - that lists all officers of that company.

3. For each officer you’re interested in you take the links.officer.appointments member and call that - that is just the link to the Officer Appointments endpoint with the “officer_appointment_id” filled in.

4. Now you have a list of appointments for that officer. Each entry in the list has a links.company member. There’s the company - the company number is right there and you can call that if you want the full company profile details.

So doing that you’ve taken a company and you can link any / all officers at that company to other companies.

No need for “officer ID” - just follow the links. (Although if for some reason you want it you can extract it from the links - see below).

Example 1 - this is exactly the same only you start from the officer’s name. You then get the list of appointments, which (as described above, step 4) give you companies that entry is an officer of.

That would seem to be what you’ve described, would it not? Unless what you’re groping for is the answer to the questions:

• But where do I get (e.g. the officer-id / appointment-id) etc? A: As mentioned it’s more helpful to think about following links. However - this being a REST API - the links are just the Companies House endpoints, minus the https://api… part, with any required values filled in. So if you know the endpoint you know what the format is and you can pull out the “variables”. Using “variables” in the “url path” is a fairly standard feature of REST APIs.

• I’ve found the following endpoint: get company office appointment. That mentions the appointment ID - where do I get it? A: See my answers above - follow the links is the way.

• Do officer appointment IDs and disqualified officer IDs correlate? A: No they don’t - I believe Companies House has answered in the negative here.

So I hope that covers it.

However you will still soon run into exactly the issue of name matching (or possibly multiple field matching). Because you’ll quickly find that in many cases Companies House has multiple separate entries for “the same” officer in its appointments data set:

Meaning of officer_id in appointmentList resource

Hi - I know that officers are not truly uniquely identified and that we might have the same entity in real life being linked to different appointments_id. Preamble to the questions is: we query the API with a certain appointment_link containing an officer_id, say: umVXYzu2PmpPehTY22bsCgQdmHA. Let’s store this json object in a variable called r. r["name"] is COMWOOD SECRETARIAL LIMITED. r["items"] contains all the actual appointments of COMWOOD SECRETARIAL LIMITED, The list of r["items"]…

Search around the forum for more oddities on this (e.g. officers with zero appointments who still appear to have them etc). If you want to be comprehensive then yes - you’re going to have to (fuzzy) match and good luck.

[mark.bowers]

Thanks very much for your reply but can I please raise a question.

You say that I do not need ‘Officer_ID’ but the Officers Appointment List API specifically calls this out as a required data item, if I do not need it, how do I call the Appointment List data?

I have trawled through the JSON and I can see the reference points you refer to, I am just confused as to how I use them to call for the date.

Thank you.

[voracityemail]

If you’re struggling here Companies House has a basic tutorial on REST APIs:

https://developer.company-information.service.gov.uk/overview

There’s a longer tutorial here:

What Is a REST API? - SitePoint

Sorry - can’t provide you with more of a step-by-step really. I mean, I could but I’m not convinced it would clarify it for you. I recommend actually trying this for yourself.

Well OK, I’ll give you the final step for example 1. (Example 2 ends the same way). Although again I recommend you actually try this. Say I took the first entry from example 1:

"links": {
                "self": "/officers/vcZz6vfqyrlqjUqezTzS7wa9rWM/appointments"
            },

(See that “vcZz6vfqyrlqjUqezTzS7wa9rWM” - that’s an officer ID. It doesn’t do me any good outside of this URL though - unlike e.g. company number you can’t fill it in anywhere else to do something.)

I just add “https://api.company-information.service.gov.uk” to the front of all that, then request this (again using curl - again in the response I’ve snipped out details and replaced with “…” for clarity):

curl -u YOUR_API_KEY: "https://api.company-information.service.gov.uk/officers/vcZz6vfqyrlqjUqezTzS7wa9rWM/appointments"

{
    "items": [
        {
            "officer_role": "corporate-llp-designated-member",
            "name": "GIBSON TULLBERG RECRUITMENT LIMITED",
            "appointed_on": "2010-06-30",
            "links": {
                "company": "/company/OC316568"
            },
            "appointed_to": {
                "company_name": "GIBSON TULLBERG LLP",
                "company_number": "OC316568",
                "company_status": "dissolved"
            },
            ...
        }
    ],
    ...
    "start_index": 0,
    "items_per_page": 35,
    "name": "GIBSON TULLBERG RECRUITMENT LIMITED",
    "is_corporate_officer": true
}

In this case there is only one item in the list - this officer is only appointed to one company. That company is given in:

• The links.company member (the company number on the end of “/company/” - OC3166568). You could add the “https://api…” part to the front of that and request it via e.g. curl and that would give you the company profile.

• The appointed_to member which saves you even needing to request the company profile - it gives you the company name, number and status here. (I can’t recall if you always get this though - but if not just call the company profile endpoint).

So there you are - example 1. We started from an officer name (“gibson”) and we got to a list of companies they are an officer of (above). To do that I called first called the /search/officers endpoint and got back a list of “gibsons”. I picked the one we wanted (the first here) and used the links.self field. I called that (which is the Officers appointments endpoint - the link just has the officer-id already filled in) and got another list - the companies they were appointed to.

If you’re still working this through “on paper” I really recommend signing up and giving it a try. The API is much clearer when you actually experiment with it. There are many ways you can access the system - search this forum for some. I recommend curl as it’s very simple and widely available. Companies House also have examples using it.

[gurnur.mahiwal]

Hi we are looking to fetch company filing documents via API from Company House. Can you please suggest on the details of the API that can be leveraged to source the Company Filings - Confirmation statement , Full Accounts and MOA/COA? Your support is really appreciated.Thanks!

[voracityemail]

I recommend you first check if you want a way to a look this up but need no more than around 600 queries per 5 minutes? (You normally need one query to look up what filings are available for a company, then for each document you wish to download you need another to get information about it, then a final one to download a single document - but the latter may be counted under a different “API”).

If you have another requirement then I recommend opening a new thread here. I recommend doing so anyway because this thread is about the Officers Appointment list and not really about getting instructions on how to download filings.

I suggest if you haven’t used this service before you take time to read the general documentation here before you move on to the specifics you will need for your particular query.

I also recommend you then use the search facility in this forum (top right corner of the site - the magnifying glass icon) which will find posts about searching the filing history and downloading documents. There may be specific help for your particular language or environment.

In particular the final part of downloading documents has some specific features which may cause difficulty. I definitely recommend some of the existing threads on this site - and not just because I wrote one or more of them !

If this API appears to suit your needs the details of the specific requests and data returned are documented in the Companies House Public Data API reference and - for downloading documents the document API.

Good luck.