Learn how to retrieve and interpret related persons from company data via API, including how to determine the most recent shareholders and authorized representatives.
The "relatedPersons" field in the API response provides information on individuals associated with a company. This data helps identify key figures such as authorized representatives, shareholders, and executives.
Understanding "relatedPersons" in the API Response
When querying company data, the "relatedPersons" field lists individuals connected to the entity. Each person entry contains key attributes, including:
-
Roles: Defines the person’s function (e.g., director, shareholder, authorized representative).
-
Date: Indicates when the role became effective.
-
Demotion: Shows whether the role is no longer active (if "demotion=true").
To determine the most relevant individuals, sort the entries by the role’s date field in descending order and filter by the desired role type.
How to Find the Most Recent Shareholder
To identify the most recent shareholders, refer to the relatedPersons and relatedCompanies fields of the company object. Each related entity has at least one associated role (found in the roles array). The date field within each role reflects when the role became effective.
To find the most recent shareholders:
- Sort
relatedPersonsandrelatedCompaniesby thedatefield in their roles. - Filter by the role type Shareholder.
- Ensure the property
dirhas the value Source, meaning the identified entity is a shareholder of the requested company (and not the other way around).
Identifying Inactive Persons
To determine whether a person is still actively associated with a company, the demotion property in the roles array should be checked:
- If the last recorded role of a person has
demotion=true, it means they have been removed from that role and should no longer be considered an active representative. - Sorting the roles by
date(ascending) allows you to find the most recent status of a person.
This method ensures that only current, authorized individuals are taken into account.
Handling Data Accuracy and Updates
The accuracy of company-related data depends on various factors:
- Regular Data Updates: The API continuously updates its database to reflect the most recent company filings.
- Source Variability: Differences in publication formats and public register structures can sometimes introduce discrepancies, which are gradually refined through manual reviews and algorithm updates.