Skip to main content
GET
Get materialized shareholders

Overview

Returns the shareholders and other relationships already stored for a person or company. This is a read of entities and entity_relationships. It does not call integrations, does not materialize new rows, and does not spend enrichment credits. Use it after automatic creation when you need the same partners later. data.shareholders on that POST is only the creation response (id, name, taxId, type of children materialized in that run). Percentage and roles live on the relationship and are returned here in shareholderInfo. QSA rows that were never turned into entities (for example a masked tax id) are not included. Those remain on Get normalized enrichment. Requires granular permission entities:read on the API key (legacy fallback entities:read).

Endpoints

Both return the same body. The organization is taken from the API key.

Authentication

Path parameters

string
Entity UUID. Use this on GET /entities/{id}/shareholders.
string
Tax id stored on the entity (CNPJ, CUIT, and so on). Digits are compared the same way as get by tax id. Use this on GET /entities/by-tax-id/{taxId}/shareholders. If several rows match, the most recently created one is used.

Query parameters

integer
default:"1"
How many ownership levels to walk for shareholders. 1 is direct owners only. Maximum 5. The list is flat and de-duplicated by entity id. Nested companies are expanded only when depth is greater than 1. relationships stays one hop from the root entity.
integer
default:"100"
Page size applied separately to shareholders and to relationships. Maximum 500.
integer
default:"0"
How many items to skip in each array. Applied after the shareholder filters.
string
Keep shareholders whose entity type is person or company. Other links in relationships are not filtered.
string
Exact tax id of a shareholder. Digits are compared, so 123.456.789-00 matches 12345678900.
number
Minimum riskScore, inclusive. Shareholders with riskScore: null are excluded when this or maxRiskScore is set.
number
Maximum riskScore, inclusive.
number
Minimum ownership percentage, inclusive. Shareholders without a stored percentage are excluded when this or maxOwnershipPercentage is set.
number
Maximum ownership percentage, inclusive.
Filters combine with AND. They apply to shareholders only, after depth is walked and before limit / offset. A company that does not match is still walked when depth is greater than 1, so a matching owner underneath it can still be returned. minRiskScore cannot be greater than maxRiskScore, and the same rule applies to the ownership bounds (400).

Response

200 with { "success": true, "data": { ... } }. Ownership links use direction shareholder = source, owned entity = target, and a type of shareholder, owns, or controls. Those go in shareholders. Every other non-deleted link where this entity is source or target goes in relationships.
string
UUID of the entity that was queried.
array
Materialized owners.
  • id, name, taxId, type, riskScore β€” the related entity. riskScore is null when the shareholder has no score. taxId is null when the API key lacks entities:read_sensitive.
  • shareholderInfo.percentage β€” metadata.shareholdingPercentage, or null
  • shareholderInfo.roles β€” metadata.roles (empty array when absent)
  • shareholderInfo.isActive β€” metadata.isActive, or null
number
Shareholders matching the filters, before limit / offset.
array
Other materialized counterparties.
  • id, name, taxId, type β€” the related entity. taxId is null when the API key lacks entities:read_sensitive.
  • relationshipType β€” link type (for example related_to)
number
Other links, before limit / offset. Filters do not change this count.
An entity with no links returns 200 and both arrays empty.

Errors

Example