Skip to main content

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

CountryCodePrice
FranceFR€2.00
United KingdomGB€2.00
BelgiumBE€2.00

​
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

typeMeaning
live_from_registryFresh pull from the official registry API
cached_from_registryCached copy of an official registry record
inferredSimple derivation from registry data (e.g., code mapping)
ai_analysisReconstructed from documents by an AI agent. Best-effort, verify before relying on it for compliance.
private_sourcePaid 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

This is a best-effort reconstruction. Use the data for initial research or screening, but verify through official channels for compliance decisions.
If your workflow needs registry-backed data only, exclude any shareholder whose dataSources.shareholders.items[i].overall.type (or any relevant fields[x].type) is ai_analysis.
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.
Use alongside ultimateBeneficialOwners for a more complete ownership picture. UBOs come from official registers where available.