Company PSC Kind types

[ABry]

In the API docs for “List resource” in the Companies House People of Significant Control API (Companies House Public Data API: list) it lists possible values for “kind” as the following:

• individual-person-with-significant-control
• corporate-entity-person-with-significant-control
• legal-person-with-significant-control
• super-secure-person-with-significant-control
• individual-beneficial-owner
• corporate-entity-beneficial-owner
• legal-person-beneficial-owner
• super-secure-beneficial-owner

But for some responses (for example using /company/SC725848/persons-with-significant-control as an example) I see “legal-person-person-with-significant-control” as the kind of the second PSC (note the word “person” is repeated).

Is this a grammatical mistake of “legal-person-with-significant-control” or some unlisted type?

[voracityemail]

You are correct - both the documentation you link to and the specification appear to be out of sync with the actual data returned. (And have been for a very long time… This is not the only place in the API where this is the case either.)

As you note this is (always?) returned as: legal-person-person-with-significant-control

… which while it looks odd makes sense given that all the other similar constants are (something)-person-with-significant-control - here the “something” is just “legal-person”.

More here:

PSC kinds - examples and corporate PSC numbers

It seems (though not yet in specification documents) that the Persons with Significant Control list resource returns a “kind” field which indicates what type of entity the entry represents. This is very useful for us and this post is a note for others as isn’t yet fully documented. Also the relevant constants don’t yet appear in the constants files. The values of “kind” would logically seem to be as indicated in the individual resources for each type of entity: Individual (person) Corporat…

Also note that the constants are not the same between APIs either e.g. apparently the Streaming API has a different set of constants (at least for PSCs).

We have found that - like all large APIs - it is a very good idea to parse results with a flexible parser:

a) Trying to assume as little as possible and handle as wide a range of “discovered data” as is logical for our application e.g. allowing that values may appear which we have no knowledge of and handling those as sensibly as possible. Also trying not to rely on particular fields (if it’s not vital to our use-case, don’t fail if it doesn’t appear at all!)

b) Logging unexpected data to feed back in to the process of “here’s what we know we may get”.

See this old thread for some examples you can check if you need (I have no idea if the speculations therein are true though).

PSC list - legal-person-with-significant-control data issues?

If my understanding of the “legal-person-with-significant-control” PSC category (“Other Registrable Person” on the forms) is correct it seems that it’s not uncommon that registrants are incorrectly using this category. Both individuals and normal corporations appear to be recorded under this category when they should be listed as “individual-person-with-significant-control” or “corporate-entity-person-with-significant-control”. Possible workarounds for API users I can’t see a “correct” way fo…

Good luck.

[frank]

Not from Companies House but our interpretation of this is that a legal person (i.e. a legal entity) is the person-with-significant-control rather than a human person.

Statbooks

[ABry]

Our usual practice when an API doc specifies lists of possible results is to deserialise into an enumerated type which is where I noticed this issue, but you are probably right that it makes more sense to be more flexible parsing this.

I did come across that thread when I searched for the rouge kind, but I didn’t see much discussion around if it is indeed a mistake, or if it does represent something different as @frank suggests below.

Thanks for the advice and confirming that it isn’t just me being confused!