Shareholders Extraction

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

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.

Alpha Feature: Best Effort ReconstructionThis 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

Supported countries

Country	Code
France	FR
United Kingdom	GB
Belgium	BE

See Coverage and pricing for live availability and pricing.

Example Request

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:

{
  "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

{
  "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

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.

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.

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.

Combine with UBO data

Use alongside ultimateBeneficialOwners for a more complete ownership picture. UBOs come from official registers where available.

Getting Started

Integration Guides

Core Features

Behavior & Operations

Shareholders Extraction

Supported countries

Example Request

Example Response

Identifying Reconstructed Shareholders

Example `dataSources` Payload

Data Source Types

In the Ownership Graph

Best Practices

​Supported countries

​Example Request

​Example Response

​Identifying Reconstructed Shareholders

​Example dataSources Payload

​Data Source Types

​In the Ownership Graph

​Best Practices

Supported countries

Example Request

Example Response

Identifying Reconstructed Shareholders

Example `dataSources` Payload

Data Source Types

In the Ownership Graph

Best Practices