Clarification on PSC API self link identifier and required field

API Issues
1

Hello Companies House Team,

I am working with the Persons with Significant Control (PSC) API and noticed that each PSC record includes a self link with an identifier at the end, like this:

“links”: {
“self”: “/company/{company_number}/persons-with-significant-control/individual/{psc_identifier}”
}

Could you please confirm the following:

  1. Is the identifier at the end of the self URL a unique and persistent ID for the PSC record, or can it change over time?
  2. Is the self link a required field in the API response? Does Companies House always include this field?

We couldn’t find detailed documentation on this and would appreciate clarification to help us manage PSC data reliably in our system.

Thank you!

2

Hi Companies House Team,

Just following up on my query from a few days ago regarding the PSC API self link identifier. We’re currently working on integrating this into our system and would greatly appreciate any guidance or confirmation on the points raised above.

3

Thank you for posting your query to the Developer Forum, we will consider along with relevant technical colleagues and respond further as soon as possible - in the meantime, the option remains available for other Forum viewers to contribute. KAJ

4

I’m not from Companies House, just another forum poster, but:

a) The design of the API seems to be more in terms of “links” and “following links” rather than being focussed on “obtain / provide IDs”. Furthermore it seems that Companies House actually maintains several data sets and (at least as far as the ID exposes) the IDs and data do not necessarily map between these (e.g. disqualified office ID has nothing to do with officer ID in the Public Data Office Appointments). Outside of the Company number I would just treat these with caution - perhaps relying primarily on your own generated ID to refer to any entities you store / process data for.

That being said I’m not aware these do change - but note there are some data/process issues * with this dataset. (Aside from those inherent in Companies House legal responsibilities as a recorder, and this being a large, long-lived public dataset.) See e.g. multiple entries for “the same” individual as a PSC etc. (you can search this forum for any other issues).

b) Many (all?) of the endpoints in the Public Data API and Document API return a links member which has a self reference. Like everything in the API (and remote APIs in general) I would not assume it will be there. In my experience it’s always sensible to parse returned data - and have some system for handling missing / unexpected responses e.g. error logging / reporting. And ideally one which can skip data that you don’t actually rely on (for many uses you won’t need the “self” link I would imagine).