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

# Shareholders Extraction

> Reconstruct probable shareholder data for countries without direct registry access

`shareholders` is a first-class data block in the Topograph data model. In countries with direct registry access (e.g., Germany, Spain), shareholder data is returned directly from official sources when you request the `shareholders` datapoint.

For countries that don't expose shareholder data directly through official registries, Topograph offers a `shareholders` datapoint that **reconstructs the most probable current shareholder structure** by analyzing available company documents.

The output format is **identical** regardless of whether the data comes from a registry or from document reconstruction. To tell them apart in the response, inspect the `dataSources` object (see [Identifying Reconstructed Shareholders](#identifying-reconstructed-shareholders)).

<Note>
  Sole entrepreneurs and non-profits have no share capital, so the `shareholders` datapoint returns an explicit `datapoint_not_applicable` response for them instead of an empty list. The owner is available under `legalRepresentatives` and `ultimateBeneficialOwners`. See [Sole Entrepreneurs & Non-Profits](/essentials/entity-types).
</Note>

<Warning>
  **Alpha Feature: Best Effort Reconstruction**

  This feature reconstructs a **plausible** shareholder structure based on available public documents. Due to the nature of incomplete public records, we cannot guarantee that:

  * **All shareholders are captured**, as some may be missing if not disclosed in available documents
  * **No extra shareholders appear**, as historical shareholders may be included if no exit was recorded
  * **Share amounts are exact**. Percentages and share counts are approximations based on available data

  This is a **best-effort reconstruction**, not authoritative registry data. Results should be verified manually for compliance or legal use cases.

  **Additional alpha limitations:**

  * Processing may take **30 seconds to several minutes**
  * Extraction may **fail or return no results** for some companies
  * Behavior and pricing may change
</Warning>

## Supported countries

| Country        | Code |
| -------------- | ---- |
| France         | FR   |
| United Kingdom | GB   |
| Belgium        | BE   |

See [Coverage and pricing](/essentials/coverage-and-pricing) for live availability and pricing.

## Example Request

```bash theme={null}
curl --request POST \
  --url https://api.topograph.co/v2/company \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <api-key>' \
  --data '{
    "countryCode": "FR",
    "id": "123456789",
    "dataPoints": ["shareholders"]
  }'
```

## Example Response

The response uses the same `shareholders` structure as countries with direct registry access:

```json theme={null}
{
  "request": {
    "requestId": "uuid-v4",
    "companyId": "123456789",
    "country": "FR",
    "dataStatus": {
      "dataPoints": {
        "shareholders": {
          "status": "succeeded",
          "cost": 200
        }
      }
    }
  },
  "shareholders": [
    {
      "type": "individual",
      "individual": {
        "name": {
          "fullName": "Jean Dupont"
        }
      },
      "sharePercentage": 60,
      "numberOfShares": 600
    },
    {
      "type": "company",
      "company": {
        "legalName": "Holding SAS",
        "countryCode": "FR",
        "id": "987654321"
      },
      "sharePercentage": 40,
      "numberOfShares": 400
    }
  ]
}
```

## Identifying Reconstructed Shareholders

Reconstructed shareholders are always tagged as AI-derived in the `dataSources` object. Registry-backed shareholders carry a `live_from_registry` or `cached_from_registry` source instead. Use this to filter or flag best-effort data in your own pipelines.

Three fields on `dataSources.shareholders` describe the reconstruction:

* `overall.type === "ai_analysis"`: the entire list was produced by document reconstruction. The `overall.analysis` field carries the agent's reasoning summary, and `overall.documents` lists the filings it relied on.
* `limitations`: a structured array of gaps the agent flagged (e.g., unparseable documents, missing share-pledge agreements). Present only when gaps were detected.
* `items[i].overall`: per-shareholder narrative explaining how that specific entity was traced. Aligned 1:1 by index with the `shareholders` array. The `entityId` field lets you match items back to shareholders without relying on order.

Per-field sources live under `items[i].fields` and use the same `type` taxonomy, so an individual field (e.g., `sharePercentage`) can be flagged as `ai_analysis` even when the rest of the entity is registry-backed.

### Example `dataSources` Payload

```json theme={null}
{
  "dataSources": {
    "shareholders": {
      "overall": {
        "type": "ai_analysis",
        "analysis": "Reconstructed from two capital-increase notices (2022, 2024) and the most recent K-bis. No share-pledge agreements available after 2024.",
        "documents": [
          { "name": "K-bis", "date": "2025-01-14" },
          { "name": "Capital increase notice", "date": "2024-03-02" }
        ]
      },
      "limitations": [
        "No filings after March 2024; subsequent transfers would not be captured.",
        "One founding-act scan was unreadable and skipped."
      ],
      "items": [
        {
          "entityId": "shareholder-1",
          "overall": {
            "type": "ai_analysis",
            "analysis": "Retained 60% after the 2024 capital increase.",
            "documents": [{ "name": "Capital increase notice", "date": "2024-03-02" }]
          }
        },
        {
          "entityId": "shareholder-2",
          "overall": {
            "type": "ai_analysis",
            "analysis": "Subscribed to 40% of shares in the 2024 round."
          }
        }
      ]
    }
  }
}
```

### Data Source Types

| `type`                 | Meaning                                                                                               |
| ---------------------- | ----------------------------------------------------------------------------------------------------- |
| `live_from_registry`   | Fresh pull from the official register                                                                 |
| `cached_from_registry` | Cached copy of an official register record                                                            |
| `inferred`             | Simple derivation from register data (e.g., code mapping)                                             |
| `ai_analysis`          | Reconstructed from documents by an AI agent. Best-effort, verify before relying on it for compliance. |
| `private_source`       | Paid or private data provider                                                                         |

### In the Ownership Graph

Reconstructed shareholders also surface inside the `graph` datapoint. Each company node whose shareholders were reconstructed carries its own block under `dataSources.graph.nodes[<nodeId>].shareholders`, with the same `overall`, `limitations`, and `items` shape documented above. This lets you spot best-effort reconstructions at any depth of the ownership tree, not just for the root company.

## Best Practices

<AccordionGroup>
  <Accordion title="Treat results as indicative">
    This is a best-effort reconstruction. Use the data for initial research or screening, but verify through official channels for compliance decisions.
  </Accordion>

  <Accordion title="Filter by source type">
    If your process needs registry-backed data only, exclude any shareholder whose `dataSources.shareholders.items[i].overall.type` (or any relevant `fields[x].type`) is `ai_analysis`.
  </Accordion>

  <Accordion title="Surface limitations to end users">
    The `dataSources.shareholders.limitations` array is written to be human-readable. Display it alongside the reconstructed list so reviewers know what the agent couldn't determine.
  </Accordion>

  <Accordion title="Combine with UBO data">
    Use alongside `ultimateBeneficialOwners` for a more complete ownership picture. UBOs come from official registers where available.
  </Accordion>
</AccordionGroup>