> ## Documentation Index
> Fetch the complete documentation index at: https://docs.gu1.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Get materialized shareholders

> Read shareholders and other relationships already materialized for an entity, without running enrichment again.

## 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](/en/api-reference/entities/create-automatic) 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](/en/api-reference/enrichment/get-normalized).

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.

```
GET https://api.gu1.ai/entities/{id}/shareholders
GET https://api.gu1.ai/entities/by-tax-id/{taxId}/shareholders
```

## Authentication

```bash theme={null}
Authorization: Bearer YOUR_API_KEY
```

## Path parameters

<ParamField path="id" type="string">
  Entity UUID. Use this on `GET /entities/{id}/shareholders`.
</ParamField>

<ParamField path="taxId" type="string">
  Tax id stored on the entity (CNPJ, CUIT, and so on). Digits are compared the same way as [get by tax id](/en/api-reference/entities/get). Use this on `GET /entities/by-tax-id/{taxId}/shareholders`. If several rows match, the most recently created one is used.
</ParamField>

## Query parameters

<ParamField query="depth" type="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.
</ParamField>

<ParamField query="limit" type="integer" default="100">
  Page size applied **separately** to `shareholders` and to `relationships`. Maximum `500`.
</ParamField>

<ParamField query="offset" type="integer" default="0">
  How many items to skip in each array. Applied after the shareholder filters.
</ParamField>

<ParamField query="type" type="string">
  Keep shareholders whose entity type is `person` or `company`. Other links in `relationships` are not filtered.
</ParamField>

<ParamField query="taxId" type="string">
  Exact tax id of a shareholder. Digits are compared, so `123.456.789-00` matches `12345678900`.
</ParamField>

<ParamField query="minRiskScore" type="number">
  Minimum `riskScore`, inclusive. Shareholders with `riskScore: null` are excluded when this or `maxRiskScore` is set.
</ParamField>

<ParamField query="maxRiskScore" type="number">
  Maximum `riskScore`, inclusive.
</ParamField>

<ParamField query="minOwnershipPercentage" type="number">
  Minimum ownership percentage, inclusive. Shareholders without a stored percentage are excluded when this or `maxOwnershipPercentage` is set.
</ParamField>

<ParamField query="maxOwnershipPercentage" type="number">
  Maximum ownership percentage, inclusive.
</ParamField>

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`.

<ResponseField name="entityId" type="string">
  UUID of the entity that was queried.
</ResponseField>

<ResponseField name="shareholders" type="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`
</ResponseField>

<ResponseField name="totalShareholders" type="number">
  Shareholders matching the filters, before `limit` / `offset`.
</ResponseField>

<ResponseField name="relationships" type="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`)
</ResponseField>

<ResponseField name="totalRelationships" type="number">
  Other links, before `limit` / `offset`. Filters do not change this count.
</ResponseField>

An entity with no links returns `200` and both arrays empty.

## Errors

| Status | Code | When |
| - | - | - |
| 400 | `INVALID_ENTITY_ID` | `id` is not a UUID |
| 404 | `NOT_FOUND` | No live entity with that id or tax id in your organization |

## Example

```bash theme={null}
curl -X GET "https://api.gu1.ai/entities/550e8400-e29b-41d4-a716-446655440000/shareholders?depth=1" \
  -H "Authorization: Bearer YOUR_API_KEY"
```

```json theme={null}
{
  "success": true,
  "data": {
    "entityId": "550e8400-e29b-41d4-a716-446655440000",
    "shareholders": [
      {
        "id": "6ba7b810-9dad-11d1-80b4-00c04fd430c8",
        "name": "João Silva",
        "taxId": "12345678900",
        "type": "person",
        "riskScore": 25,
        "shareholderInfo": {
          "percentage": 60,
          "roles": ["Sócio Administrador"],
          "isActive": true
        }
      }
    ],
    "totalShareholders": 1,
    "relationships": [
      {
        "id": "6ba7b811-9dad-11d1-80b4-00c04fd430c8",
        "name": "Carlos Lima",
        "taxId": "55566677788",
        "type": "person",
        "relationshipType": "related_to"
      }
    ],
    "totalRelationships": 1
  }
}
```


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.