First two questions - as @tcunha says.
In psc_descriptions whats is difference between description, short_description, statement_description and super_secure_description?
Note: the first place to look for info should be:
- The CH API documentation - although it is "a work in progress" e.g. incomplete and sometimes out of date.
- Search on this forum.
Right, (assuming you are referring to the PSC enumeration constants):
The description, short_description, statement_description and super_secure_description are 4 different things. Actually 3 different things as description and short_description give alternative values for the same constant returned by CH.
What do they mean / what relations do they describe?
Again this is covered by documentation, the info on this forum (e.g. http://forum.aws.chdev.org/t/psc-streaming-api/529 ) and UK company regulations e.g. PSC reporting requirements.
- If you want to find which persons - human or corporate / legal entity - have significant control for a particular company, call the "List the company persons with significant control" endpoint. This will return a list resource. This lists people, companies or legal persons who have control. For each item it lists one or more natures of control.
- In the list are also super secure persons which are PSCs where information is legally restricted. You can only see that they exist and if there was one but one they have ceased to have control. There is a
description field but this only has one value at the moment.
- If the list resource has a
links field this may indicate if PSC statements are available e.g.:
"persons_with_significant_control_statements_list" : "a link to the PSC statementList"
If this field exists then calling the "list statements" endpoint should return a statementList resource. (You can just use the link you get
links in above). These are statements about the PSCs or rather why PSC details are missing. Roughly these fall into categories "there are no PSCs", "the company is checking to see if there are any" and "there is some problem getting info from PSC(s)".
How are they used?
The documentation describes this - if that was your question - but here's a quick overview:
There's a field called
natures_of_control which is returned as part of the corporateEntity resource, individual resource and legalPerson resource.
It's also returned for each item in the PSC list resource. (The list resource holds an array of objects of one of the three types just metioned [plus super-secures - more on that later]. The field
kind tells you which type you have.)
natures_of_control field is an array of strings and each value should match an entry in the psc_descriptions -> description or psc_descriptions -> short short_description constants.
The same idea as above but this time it's the
statement field returned as part of the
statement resource. Again like above you can get the statementList resource which holds an array of statement resources if there is more than one.
statement field is is an array of strings and each value should match an entry in the psc_descriptions -> statement_description constants.
If you request the PSC list resource then any "super secure PSCs" are also listed. These come in the form of a superSecure resource. The value of the kind field for these is
super-secure-person-with-significant-control. There is a
description field which contains a string and you can look this up in the psc_descriptions -> super_secure_description constants. It's not very helpful at the moment as there is only one value!
P.S. you may be wondering how you know if a company has PSCs / statements without having to call the PSC endpoints blindly. The company profile resource may have (in the
links section) the following fields:
I'm not sure these are both necessary and sufficient to indicate the presence / absence of this data however.