Ownership Graph

Traverse multi-level ownership structures across countries automatically

The graph datapoint builds a complete ownership tree by recursively fetching shareholders across multiple countries and traversal depths. Starting from a root company, Topograph follows corporate shareholder chains (resolving each company in its local registry) to produce a full graph of entities and ownership relationships.

The result includes UBO (Ultimate Beneficial Owner) calculations based on ownership thresholds.

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": "AT",
    "id": "36416d",
    "dataPoints": ["graph"],
    "graphMaxBudget": 500
  }'

How It Works

1. Root fetch: Retrieves the company profile and shareholders from the root company’s registry
2. Shareholder resolution: For each corporate shareholder, searches the relevant country’s registry to find the company
3. Recursive traversal: Fetches shareholders for each resolved company, building the tree level by level
4. UBO calculation: Identifies individuals with >25% ownership through direct or indirect chains

The traversal runs breadth-first with bounded concurrency. Each level completes before the next starts.

Traversal Limits

The graph traversal has built-in limits to control scope and cost:

Limit	Default	Description
Budget	Set by caller via graphMaxBudget	Maximum credit cents to spend on company lookups during traversal. The primary control for graph scope.
Max depth	10 levels	Maximum depth of shareholder chain to follow
Max entities	500	Maximum total entities (companies + individuals) in the graph
Execution timeout	6 hours	Safety net for stuck traversals. Should never be reached in normal operation

When any limit is reached, the graph returns all data collected up to that point with a stoppedReason indicating why traversal stopped.

Need higher limits? If your use case requires deeper traversals or more entities, contact us to discuss your requirements.

Stopped Reasons

The metadata.stoppedReason field indicates how the traversal ended:

Reason	Meaning
completed	All shareholder chains were fully resolved
budget_exhausted	The graphMaxBudget limit was reached
max_depth_reached	Maximum traversal depth was reached
max_nodes_reached	Maximum entity count was reached
timeout	Execution timeout was reached (indicates a system issue)

Response Structure

The graph result is included alongside the standard company data:

{
  "request": {
    "requestId": "uuid-v4",
    "companyId": "36416d",
    "countryCode": "AT",
    "dataStatus": {
      "dataPoints": {
        "graph": { "status": "succeeded" }
      }
    }
  },
  "graph": {
    "nodes": [
      {
        "nodeId": "AT:36416d",
        "type": "company",
        "flags": {
          "isRoot": true,
          "status": "found",
          "isUbo": false
        },
        "company": {
          "legalName": "Example Handels GmbH",
          "countryCode": "AT",
          "id": "36416d"
        }
      },
      {
        "nodeId": "FR:301189718",
        "type": "company",
        "flags": {
          "isRoot": false,
          "status": "found",
          "isUbo": false,
          "isUboProxy": true
        },
        "company": {
          "legalName": "Holding Internationale",
          "countryCode": "FR",
          "id": "301189718"
        },
        "totalOwnershipPercentage": 61
      }
    ],
    "edges": [
      {
        "id": "AT:36416d->FR:301189718",
        "fromId": "AT:36416d",
        "toId": "FR:301189718",
        "percentage": 61,
        "source": "Extracted from trade register extract"
      }
    ],
    "description": "Ownership graph with 2 entities and 1 relationship.",
    "metadata": {
      "stoppedReason": "completed",
      "amountSpent": 200,
      "companiesFetched": 2,
      "companiesSkipped": 0
    }
  }
}

Node Flags

Flag	Type	Description
isRoot	boolean	The company that was originally requested
status	string	found, pending, not_found, error, placeholder, search_resolved, budget_truncated
isUbo	boolean	Individual with >25% direct or indirect ownership
isUboProxy	boolean	Company through which UBO ownership flows

A node with status: "budget_truncated" is a placeholder for a corporate shareholder the traversal did not fetch (because of graphMaxBudget, graphInteractive, or a depth/entity limit). It carries the nodeId and a cost preview, and can be passed to graphContinueFromNodeIds in a follow-up request to resume from there.

Interactive mode

Set graphInteractive: true to fetch only the entry company and return its direct shareholders. Companies among those shareholders come back as budget_truncated placeholders so the caller decides which branches to expand. Each chip click is one fetch and one billing event.

curl --request POST \
  --url https://api.topograph.co/v2/company \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <api-key>' \
  --data '{
    "countryCode": "AT",
    "id": "36416d",
    "dataPoints": ["graph"],
    "graphInteractive": true
  }'

graphInteractive and graphMaxBudget are mutually exclusive. When graphInteractive is true, the budget value is ignored.

The response carries graph.metadata.interactive: true so a stored result is self-describing, and graph.metadata.stoppedReason reads max_depth_reached.

Continuing from a previous request

To extend a graph from one or more budget_truncated placeholders, pass their nodeIds in graphContinueFromNodeIds and link to the parent through mainRequestId. countryCode and id are derived from the parent automatically.

curl --request POST \
  --url https://api.topograph.co/v2/company \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <api-key>' \
  --data '{
    "dataPoints": ["graph"],
    "mainRequestId": "<previous-request-id>",
    "graphContinueFromNodeIds": ["FR:301189718"]
  }'

Cost deduplication applies across the full request tree: companies already fetched in the parent (or a sibling continuation) are not re-billed.

If the parent request was made with graphInteractive: true, every continuation inherits the flag. The seeded node is fetched and its own direct shareholders are surfaced as a fresh layer of placeholders, ready for the next click.

Best Practices

Pick the right control: budget vs. interactive

Use graphMaxBudget when you want a single response with as much of the tree as fits within a known cost ceiling. Use graphInteractive when you want predictable per-step cost and a deterministic UI: one fetch per request, the rest of the tree visible only as continuation handles you choose to expand.

Set an appropriate budget

The graphMaxBudget parameter is the primary way to control non-interactive traversal scope. Start with a lower budget for exploration, then increase if you need deeper coverage. Each company lookup costs the standard price for that country.

Expect variable execution times

Graph traversal time depends on the number of companies, the countries involved, and registry response times. Simple structures (1-2 levels, single country) complete in seconds. Complex multi-country structures with deep chains can take several minutes. Interactive requests are bounded by a single company fetch, so they return as fast as that country’s registry replies.

Handle partial results

When a limit is reached, the graph returns everything collected so far. Check metadata.stoppedReason to understand why traversal stopped and whether requesting again with a higher budget, or extending via graphContinueFromNodeIds, would yield more data.