API Data Meanings

API Question
#1

Researching in order to use the Companies House Public Data API but needing to understand what the following data items logically map to/mean - any help appreciated.

API Endpoint: GET /company/{company_number}/registers

  • Company register > Registers > Directors > items[] - What does “moved_on” mean? Is this he date the director was appointed or resigned?

  • Company register > Registers > Members - Is “register_type” the Company Type e.g. Private Limited Company?

  • Company register > Registers - For “persons_with_significant_control” a number of data items are provided, which field contains the name of the person with control?

  • Company register > Registers - For “persons_with_significant_control” is the “moved_on” date the “notified on” date?

  • Company register > Registers > Persons with significant control - What does the “register_type” mean in relation to the person of significant control?

API Endpoint: GET /officers/{officer_id}/appointments

  • Appointment list - Is the “total_results” the count of all officers? Does this include both active and resigned?

API Endpoint: GET /company/{company_number}/persons-with-significant-control

  • For the PSC list, what does the data item “active_count” represent? I assume this is just the active persons with significant control
  • For the PSC list, what does the data item “total_results” represent? Is this all active persons of control or does this include inactive also?
#2

I think this is covered by the documentation (I’ll link to each part below). However depending on your level of knowledge of UK Companies and company law that may not always be very helpful. The Companies House API doesn’t (as far as I am aware) come with a single handy guide to UK company law or more specifically how the law relates to what the values recorded mean and when / why they are recorded! There are various pages with information - however this is normally written for those actually filing for companies, not third-parties interacting with the data set.

So:

API Endpoint: GET /company/{company_number}/registers - I think this is mostly covered by the documentation. There is a general overview of Company Registers at Companies House which may be helpful background information.

If you are actually seeking the names of directors, secretaries or Persons with significant control you should use the appropriate endpoints for that company e.g. the Officers list for the first two and the PSC list for the last. The registers endpoint simply tells you about where registers are kept (and I think only in cases where something unusual was done e.g. the company decided to keep its own registers).

API Endpoint: GET /officers/{officer_id}/appointments - the documentation covers this e.g. this is indeed the total of everything in the list. This is so you can “page” through them e.g. Companies House may not return all the results in a single request. You should count the items you have received and compare this to the total_results - if less, then there is more data you can request (e.g. by adjusting the start_index parameter - search the forum for that and / or “paging” if you’re not sure about how to do this).

API Endpoint: GET /company/{company_number}/persons-with-significant-control - again see the documentation and the comment on total_results above.

Hope this helps.